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Introduction 

This manual describes these libraries included with THINK C: 

• ANSI 

• console 

• unix 

Topics covered In this chapter: 

• The libraries 


The Libraries 

The libraries are supplied in project form so the smart linker can create the smallest code 
possible. The source code for all the standard libraries is in your THINK C package, so you 
can modify the routines to suit your programs. 

This is the complete list of libraries described in this manual (found in the C Libraries 
folder): 


ANSI 

ANSI-881 
ANSI-small 
ANSI-A4 
console 
unix 


The ANSI standard library. 

The ANSI standard library for machines with the MC68881. 

A subset of ANSI, without console or floating-point support. 
A subset of ANSI-small, for non-applications (drivers, etc.). 
Advanced console-handling functions. 

Common Unix routines not in the ANSI standard library. 


A function index is in the back of this manual to help you quickly locate any function you 
need. 
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Introduction 

This chapter lists the contents of the header files for the ANSI library. 

Topics covered in this chapter: 

• What’s in the listing 

• A listing of the ANSI header files 


What’s in the Listing 

The following listing contains the various types, macros, and functions declared in the 
header files for the ANSI library. 

For each header file... 

For most macros describing constant values, the listing includes their values in THINK C and 
descriptions. Floating-point values are rounded to five decimal places. 

For most macros with arguments, the listing includes just a description. Most have more ex¬ 
tensive documentation in Chapter 3, “ANSI.” 

For most types, the listing includes their definitions in THINK C and descriptions. Type defi¬ 
nitions for the lengthier structs (generally, those that don’t fit in one line) aren’t included. 

For functions, the listing includes just the name. More extensive documentation is in Chapter 
3, “ANSI.” 

The header files 

These header files are for the ANSI library: 


assert.h 
ctype. h 
errno. h 
float. h 
limits.h 
locale.h 
math.h 
setjmp. h 


signal.h 
stdarg.h 
stddef.h 
stdio.h 
stdlib. h 
string. h 
t ime. h 
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DESCRIPTION 

TYPES 

MACROS 

FUNCTIONS 


<assert.h> 

For putting diagnostic messages in your programs. 

None, 
assert() 

For more information, read the assert () section in the ANSI chapter 
None. 


4 



ANSI Header Files 


2 


DESCRIPTION 

TYPES 

MACROS 

FUNCTIONS 


<ctype.h> 

For testing and mapping characters. 
None. 

None. 


These functions are declared in ctype. h: 


isalnum() 
isdigit() 
isprint () 
isupper() 
toupper() 


isalpha() 
isgraph() 
ispunct () 
isxdigit () 


iscntrl() 
islower() 
isspace() 
tolower() 
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DESCRIPTION 

TYPES 

MACROS 


FUNCTIONS: 


<errno.h> 


Macros for error-reporting. 
None. 


Macro 

Value 

Description 

EDOM 

33 

A domain error occurred, i.e., 
the value passed to this function 



was erroneous. 

ERANGE 

34 

A range error occurred, i.e., the 
value that this function gener¬ 
ated was erroneous. 

errno 

Contains an error number, which various functions 
set when they encounter errors. 


None. 


6 



ANSI Header Files 


2 


DESCRIPTION 

TYPES 

MACROS 


<float.h> 


Limits and other parameters for floating-point numbers. 
None. 


Macro 

Value 

Description 

FLT_RADIX 

2 

The radix for an exponent in a 
floating-point number 

FLT_ROUNDS 

1 

A code specifying how floating¬ 
point functions round the results 
of addition. THINK C rounds to 
the nearest integer. 


These macros define some limits and other parameters for floating-point 
numbers. Macros beginning with FLT are for numbers of type float; DBL, 
double; and LDBL, long double. In this chart, all floating-point values are 
rounded to five decimal places. 


Macro 

Value 

Description 

FLT MANT DIG 

24 

The number of base 

DBL MANT DIG 

64 

FLT_RADIX digits in the 

LDBL_MANT_DIG 

64 

floating-point significand. 

FLT DIG 

6 

Decimal digits of 

DBL_DIG 

18 

precision 

LDBL_DIG 

18 


FLT MIN EXP 

-125 

The largest integer that 

DBL MIN EXP 

-16382 

can be a negative expo- 

LDBL_MIN_EXP 

-16382 

nent, when the radix is 



FLT_RADIX. 

FLT_MIN_1 0_EXP 

-37 

The largest integer that 

DBL_MIN_10_EXP 

-4931 

can be a negative expo¬ 

LDBL_MIN_10_EXP 

-4931 

nent, when the radix is 



10 . 

FLT_MAX_EXP 

128 

The largest integer that 

DBL_MAX_EXP 

16384 

can be a positive expo¬ 

L D B L_MAX_E X P 

16384 

nent, when the radix is 



FLT_RADIX. 
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FLT_MAX_ 10 _EXP 

DBL_MAX_ 10 _EXP 

LDBL_MAX_ 10 _EXP 

38 

4932 

4932 

The largest integer that 
can be a positive expo¬ 
nent, when the radix is 

10. 

FLT_MAX 

DBL_MAX 

LDBL_MAX 

3.402 82E+38 

1.18973E+4932 

1.18973E+4932 

The largest representable 
floating-point number 

FLT_EP SILON 

D BL_E P SILON 
LDBL_EPSILON 

1.19209E-7 

1.08420E-19 

1.08420E-19 

The smallest fraction that 
can be represented in 
floating point notation 

FLT_MIN 

DBL_MIN 

LDBL_MIN 

1.17549E-38 

IE-4915 

IE-4915 

The smallest normalized 
positive floating-point 
number. 


FUNCTIONS: 


None. 
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DESCRIPTION 

TYPES 

MACROS 


<limits.h> 

Limits and other parameters for integers. 

None. 

These macros define limits and other parameters for integers: 


Macro 

CHAR_BIT 

MB_LEN_MAX 

SCHAR_MIN 

SCHAR_MAX 

UCHAR_MAX 

CHAR_MIN 

CHAR_MAX 

SHRT_MIN 

SHRT_MAX 

USHRT_MAX 

INT_MIN 
INT_MAX 
UINT_MAX 
LONG_MIN 
LONG_MAX 
ULONG MAX 


Value Description 

8 Number of bits for the smallest object 

that is not a bit-field. 


1 

-128 

127 

255 

-128 

127 

-32768 

32767 

65535 

-32768 

32767 

65535 

-2147483648 

2147483647 

4294967295 


The maximum number of characters 
that can be in a multi-byte character. 
Minimum value for a signed char 
Maximum value for a signed char 
Maximum value for a unsigned char 
Minimum value for a char 
Maximum value for a char 
Minimum value for a short int 
Maximum value for a short int 
Maximum value for an unsigned 
short int 

Minimum value for an int 
Maximum value for an int 
Maximum value for an unsigned int 
Minimum value fora long int 
Maximum value for a long int 
Maximum value for an unsigned 
long int 


FUNCTIONS 


None. 
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DESCRIPTION 

TYPES 

MACROS 


FUNCTIONS: 


<locale.h> 

For localizing programs. 

Note: This is provided for ANSI C compatibility only. THINK C 
supports only the minimal "C" locale. 


lconv A structure containing information related to the 

formatting of numeric values. 

These macros are for use in the category argument of the 
setlocaleO function: 


Macro 

Value 

Description 

LC_ALL 

-1 

When set, causes all the cate¬ 
gories to comply with the rules 
for the same locale. 

LC_COLLATE 

0 

Affects the behavior of the 
strcoll () and strxfrm() 
functions. 

LC_TYPE 

1 

Affects the behavior of the char¬ 
acter-handling functions and the 
multi-byte functions. 

LC_MONETARY 

2 

Affects the monetary formatting 
information that 
localeconv 0 returns. 

LC_NUMERIC 

3 

Affects the decimal point charac¬ 
ter for the formatted output and 
string conversion functions. 

LC_TIME 

4 

Affects the behavior of the 
strftime() function. 


These functions are declared in locale, h: 


localeconv() setlocaleO 


10 



ANSI Header Files 


2 


DESCRIPTION 

TYPES 

MACROS 

FUNCTIONS 


<math.h> 


Declares several mathematical functions. 

None. 

Macro Value Description 

HUGE_VAL INF Represents Infinity. 

These functions are declared in math. h: 


acos () 

asin() 

atan() 

atan2 () 

ceil() 

cos () 

cosh() 

exp () 

fabs () 

floor() 

fmod() 

frexp() 

ldexp() 

log () 

loglO () 

modf() 

pow () 

sin () 

sinh() 

sqrt () 

tan () 


tanh () 
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DESCRIPTION 

TYPES 

MACROS 

FUNCTIONS 


<setjmp.h> 

For non-local jumps. 

Type Definition Description 

jmp_buf long X [ 11 ] An array suitable for holding the 

information that is necessary to 
restore a calling environment. 

None. 

These functions are declared in set jmp. h: 
longjmpO set jmp () 
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DESCRIPTION 

TYPES 


MACROS 


FUNCTIONS 


<signal.h> 


For handling signals. 


Type Definition Description 

sig_atomic_t int The largest type that can be writ¬ 

ten without being interrupted, 
e.g., by a signal. 

Use these macros as the second argument to (and with the return value 
from) signal (). These macros compare unequally to the address of any 
declarable function: 


Macro Value 

SIG_DFL 0 

SI G_E RR -1 

SIG IGN 1 


Description 

Perform default handling of the 
signal. 

signal () reports this as its 
error when it fails. 

Ignore the signal. 


Use these macros as the First argument (which is the signal) to the 
signal () call. They expand to the signal numbers that correspond to 
the conditions listed here: 


Macro Value 

SIGABRT 1 

SIGFPE 2 

SIGILL 3 

SIGINT 4 

SIGSEGV 5 

SIGTERM 6 


Description 

Abnormal termination 

An erroneous arithmetic opera¬ 
tion, e.g. a zero divide. 

An invalid function image, e.g., 
an illegal instruction. 

Interactive attention, e.g., inter¬ 
rupt. 

Invalid access to storage. 

The sender wants the receiver to 
terminate itself. 


These functions are declared in signal. h: 


raise () 


signal () 
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TYPES 


MACROS 


<stdarg.h> 

Type Definition Description 

va_list void * Variable argument list. Holds a 

list of arguments that may vary 
in number and type. 

These macros are declared in stdarg. h: 
va_start() va_arg() va_end() 


FUNCTIONS 


For more information on these macros, read their section in the ANSI 
chapter. 

None. 
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DESCRIPTION 

TYPES 


MACROS 


FUNCTIONS 


<stddef.h> 

Some commonly-used definitions. 

Type Definition Description 

pt rdi f f _t 1 ong The result of subtracting two 

pointers. 

size_t unsigned long The size of a C object. 

wchar_t char A member of an extended 

character set. 

Note: In THINK C, the type that sizeof returns is int, not 
size_t. 

Macro 

NULL 

offsetof() 


Value Description 

(void *) 0 The NULL pointer constant. 

The expression has the value of the offset from the 
beginning of a structure to the beginning of a struc¬ 
ture member. The units of the offset are in bytes. 
This takes two arguments: the structure type type 
and the member name member-designator. 


None. 
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<stdio.h> 

DESCRIPTION For performing input and output. 

TYPES Type Definition Description 

size_t unsigned long The size of a C object (Original 

declaration is in stddef. h.) 

fpos_t unsigned long An object that can uniquely 

specify every position within a 
file. 

FILE A structure to record all the information necessary to 

control a stream. 

MACROS These macros are defined in stdio. h: 


Macro 

Value 

Description 

NULL 

(void *) 0 

The NULL pointer. (Original 
declaration is in stddef . h.) 

BUFSIZ 

512 

The size of the buffer that 
setbuf () uses. 

EOF 

-1 

The end-of-file. 

FOPEN_MAX 

15 

The maximum number of files 
that can be open simultaneously. 

FILENAME_MAX 

256 

The length of the longest file¬ 
name, in characters. 

L_tmpnam 

20 

The length of the longest file¬ 
name string tmpnam () can 
generate. 

TMP_MAX 

9999 

The maximum number of 
unique filenames that 
tmpnam () can generate. 
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FUNCTIONS: 


These are the standard I/O streams: 


s t de r r The standard error stream, 

stdin The standard input stream, 

stdout The standard output stream. 


Use these in f seek () calls as the third argument, specifying the place 
from which to start seeking: 


Macro 

Value 

Description 

SEEK_SET 

0 

The beginning of the File 

SEEK_CUR 

1 

The current value of the file 
sition indicator 

SEEK END 

2 

The end of the File 


Use these in setvbuf () calls as the third argument, indicating how 
buffer: 

Macro 

Value 

Description 

_IOFBF 

0 

Fully buffered. 

_IOLBF 

1 

Line buffered 

_IONBF 

2 

Not buffered. 

These functions are declared in stdio. 

.h: 

_getc () 

_putc () 

clearerr() 

fclose () 

feof () 

ferror() 

fflush() 

fgetc() 

fgetpos() 

fgets() 

fopen() 

fprintf() 

fputc() 

fputs() 

freadO 

freopen() 

fscanf() 

fseek() 

fsetpos() 

ftell() 

fwrite() 

getc () 

getchar() 

gets () 

perror() 

printf() 

putc () 

putchar() 

puts() 

remove() 

rename() 

rewind() 

scanf() 

setbuf() 

setvbuf() 

sprintf() 
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sscanf () tmpfileO 

ungetc () vfprintfO 

vsprintf() 

These functions are also defined as macros: 

feof() ferror() 

getchar () putc() 


tmpnam() 
vprintf() 


getc () 
putchar () 
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DESCRIPTION 

TYPES 


MACROS 


FUNCTIONS 


<stdlib.h> 


General utilities 

Type Definition Description 


div_t struct 

{int quot. 

rem) What div () returns. 

ldiv_t struct 

{long quot. 

rem) What ldiv () returns. 

size_t unsigned long 

The size of a C object 
(Original declaration is in 
stddef. h.) 

wchar t char 


A member of an extended 
character set. (Original dec¬ 
laration in stddef. h.) 

Macro 

Value 

Description 

EXIT_FAILURE 

-1 

Return unsuccessfully. Use as an 
argument to exit (). 

EXIT_SUCCESS 

0 

Return successfully. Use as an 
argument to exit (). 

RAND MAX 

3267 

The maximum value that 
rand () will return. 

MB_CUR_MAX 

1 

The maximum number of bytes 
in a multi-byte character. 

These functions are declared instdlib.h: 

abort() 

abs () 

atexit () 

atof () 

atoi() 

atol () 

bsearch() 

calloc() 

div () 

exit() 

free() 

getenv() 

labs() 

ldiv() 

malloc () 

mblen() 

mbstowcs() 

mbtowc() 

qsort() 

rand() 

realloc() 

srand() 

strtod() 

strtol () 

strtoul() 

system() 

wcstombs() 


wctomb() 
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DESCRIPTION 

TYPES 

MACROS 

FUNCTIONS 


<string.h> 

For handling strings. 

Description 

The size of a C object. (Original 
declaration is in stddef. h.) 

Description 

The NULL pointer. (Original 
declaration is in stddef. h.) 

These functions are declared in string. h: 


Type 

Definition 

size t 

long int 

Macro 

Value 

NULL 

(void *) 0 


memchr() 
memmove() 
strcfrm() 
strcoll() 
strerror() 
strncmp() 
strrchr() 
strtok() 


memcmp() 
memset() 
strchr() 
strcpy () 
strlen() 
strncpy() 
strspn() 


memcpy() 
strcat () 
strcmp() 
strcspn() 
strncat () 
strpbrk() 
strstr () 
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<time.h> 

DESCRIPTION For manipulating time. 

TYPES Type Definition Description 

clock_t unsigned long The clock time. 

time_t unsigned long The calendar time, 

tm A structure for a broken-down time, which includes 

the month, day, year, hour, minute, and second. 

MACROS Macro Value Description 

NULL (void *) 0 The NULL pointer. (Original 

declaration is in stddef . h.) 

FUNCTIONS These functions are declared in time . h: 

asctimeO clock () ctime() 

difftimeO gmtime() localtime () 

mktime() strftime() time() 
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Introduction 

This chapter describes THINK C’s ANSI library and includes a complete catalogue of the 
functions it contains. 

Topics covered in this chapter: 

• What is the ANSI library? 

• The console package. 

• Other ANSI library configurations. 

• The catalogue of functions. 

What Is the ANSI Library? 

THINK C’s ANSI library is a complete implementation of the ANSI standard library. It 
includes functions to perform file and screen I/O, string-handling, math, and more. The 
standard gives all C programmers in all ANSI C environments a consistent set of functions, 
making programs easier to port. 

Using the ANSI library 

To use a function in the ANSI library, add the ANSI library to your project. Then, look up 
the function in this chapter’s catalogue, note the header file ^included in the Syntax section, 
and #include that file in your file. 

Multi-byte characters and locales 

For the multi-byte character and locale functions, THINK C implements only the minimum 
functionality required by the ANSI standard. All the multi-byte character and locale functions 
are in the ANSI library. But the maximum length for a multi-byte character is one byte. 
Similarly, the only locale THINK C supports is the minimal "C" locale. 

The Console Package 

THINK C’s ANSI library includes the console package. This package emulates a glass 
terminal and lets you easily port programs from a Unix or MS-DOS environment to the 
Macintosh. 

If your application performs I/O to the stdin, stdout, or stderr streams, the console 
package creates a window and menu bar for you. The I/O the application performs to these 
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streams (using, for example, print f () or getc ()) happens in the console window. The 
menu bar gives you access to all your desk accessories and the ability to cut to and paste 
from the console window. For an example of an application that uses the console package in 
the ANSI library, see Chapter 3 of the THINK C User’s Manual, “Tutorial: Hello World.” 

Using the console library, you can have more control over the console window and create 
even more of them. For more information, see Chapter 4, “console.” 

You can use the ANSI library in applications that don’t use the console package. For 
example, you may want to use the string-handling functions (such as sprintf () or 
strcmp ()) or math functions (such as at an ()) in the ANSI standard library. As long as 
you do not perform I/O to the stdin, stdout, orstderr streams, the console package 
will not be invoked. 

Other ANSI Library Configurations 

These other libraries are available for certain special cases. 

ANSI-881 

The ANSI - 8 81 library is for applications that will run only on Macintoshes with the 
MC68881 math co-processor. All the floating-point functions in this library use the MC68881. 

ANSI-small 

The ANSI - small library is for applications that do not use the full functionality of the 
complete ANSI library. It is smaller than the ANS I library, and applications that use ANSI- 
small will probably be smaller as well. 

This library does not contain the console package and the floating-point functions. Also, the 
%f floating-point conversion is not available for print f (), scanf (), and other related 
functions. 

ANSI-A4 

The ANSI-A4 library is a subset of the ANSI-small library for non-applications (desk 
accessories, code resources, etc.). The ANSI, ANSI-881, and ANS I-small libaries should 
be used in applications only. 

Not only does this library exclude the console package, the floating-point functions, and the 
%f conversion; it also excludes all functions that cannot be used outside of applications, 
such as File I/O functions. This library does include the string handling functions, such as 
sprintf () and sscanf (), in addition to many other functions. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


_atexit 

ANSI 

#include<stdlib.h> 

int _atexit (void (*func) (void)); 

_atexit () adds the function pointed by f unc to a list of functions to 
be called without arguments at normal or abnormal program termination. 

A program terminates abnormally if it calls abort (), _exit (), or 
ExitToShell () 

This function is a THINK C extension that is not in the ANSI standard. 
Zero, if the routine could add the function to the list. 

Non-zero, if it could not. 
atexit () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


_exit 

ANSI 

#include<stdlib.h> 
void _exit (int status); 

_exit () terminates the program abnormally. 

_exit () executes all functions registered with _atexit (), flushes all 
open output streams, closes all open files, and removes all temporary 
files. 

The status argument is ignored. 

This function is a THINK C extension that is not in the ANSI standard, 
exit (), abort() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


_exiting 

ANSI 

#include <stdlib.h> 
void _exiting(int i) ; 

_exiting () executes the routines done when a program exits without 
exiting a program. You can use _exiting () when you use Launch () 
or any other routine that exits a program without executing the exiting 
routines. 

Whether _exiting () _performs the routines for a normal or an 
abnormal exit is determined by the value of i: 

If i Is... _exiting () executes the routines for a... 

1 Normal exit (i.e., executes all functions registered with 

_atexit () or atexit (), flushes all open output 
streams, closes all open files, and removes all temporary 
files.) 

0 Abnormal exit (i.e., executes all functions registered with 

_atexit (), flushes all open output streams, closes all 
open files, and removes all temporary files.) 

This function is a THINK C extension that is not in the ANSI standard. 

_exit(), abort(),exiting() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


abort 

ANSI 

#include <stdlib.h> 
void abort(void); 

abort () causes the calling program to terminate abnormally. 

abort () executes all functions registered with _atexit (), flushes all 
open output streams, closes all open files, and removes all temporary 
files. 

abort () returns no special information to the host environment to 
denote unsuccessful/abnormal program termination. 

If abort () cannot abort the program, it sends the program the signal 
SIGABRT (whose purpose is essentially notification). 

If the program responds to SIGABRT, and if the resulting signal handler 
function does not return (e.g., calls long jmp ()), the program will not 
terminate. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


abs 

ANSI 

#include <math.h> 
int abs(int i); 

abs () computes the absolute value of its argument. 
I i I for any integer i. 
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acos 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


♦include <math.h> 
double acos(double x) ; 

acos () computes the principal value of the arc cosine (cos -1 ) of x, for 
any x in the range -1 to +1. 

cos -1 x in the range 0 to tc radians, if successful 

0 (zero), if I x I is greater than 1. It also sets errno to EDOM . 
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asctime 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


#include<time.h> 

char *asctime(struct tm *timeptr) 

asctime () converts into a string the broken-down time that resides in 
the structure that timeptr points to. The string has the form (for 
example): 

Tue Mar 11 01:03:52 1989\n\0 
A pointer to the string containing the time. 
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as in 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ANSI 

#include <math.h> 
double asin(double x); 

a sin () computes the principal value of the arc sine (sin -1 ) of x, for any 
x in the range -1 to +1. 

sin _1 x in the range -tt/ 2 to +tc/ 2 radians, if successful. 

0 (zero), if I x I is greater than 1. It also sets errno to EDOM. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


assert 

ANSI 

#include <assert.h> 

void assert(int expression); 

assert () asserts an expression. If the expression is false (that is, equals 
0 (zero)), assert () prints an error message to stderr about this failed 
call and calls abort (). 

assert () is useful for putting diagnostics into a program. It reports its 
failure in the following format: 

Assert failed: expression, file filename, line num 

To remove the assert () calls when you’re finished debugging, you 
don’t need to remove the actual statements. Instead, use one of these 
methods: 

• To remove them from a whole file, place a #define NDEBUG 
statement just before the #include <assert. h> statement. 

• To remove them from a region of a file, place a #define NDEBUG 
statement at the beginning of the region, and a #undef NDEBUG 
statement at the end of the region. Be sure that the region does not 
contain the #include <assert. h> statement. 
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atan 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ANSI 

#include <math.h> 
double atan(double x); 

atan () computes the principal value of the arc tangent (tan -1 ) of x. 
tan _1 x, in the range -n/2 to +ti/ 2 radians. 
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DESCRIPTION 


RETURNS 


atan2 

ANSI 

#include <math.h> 

double atan2(double y, double x); 

atan2 () computes the principal value of the arc tangent (tan -1 ) of y /x. 
It uses the signs of both arguments to determine the quadrant of the 
return value. 

tan -1 (y/x) in the range -k to +tc radians, if successful. 

0 (zero), if both x and y are 0 (zero). It also sets errno to EDOM. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


atexit 

ANSI 

#include<stdlib.h> 

int atexit (void (*func) (void)); 

atexit () adds the function pointed by f unc to a list of functions to be 
called without arguments at normal program termination. This function 
will not be called at abnormal program termination; i.e., when the 
program calls abort (), _exit (), or ExitToShell (). 

These are the conditions for normal program termination: 

• The program returns from main () 

• The program calls exit (). 

_atexit() 
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LIBRARY 


atof 

ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <stdlib.h> 
double atof(char *nptr) 

atof () converts the string to which nptr points to its double-precision 
floating point equivalent. 

The converted double-precision floating point value. 
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atof 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <stdlib.h> 
double atof(char *nptr) 

atof () converts the string to which nptr points to its double-precision 
floating point equivalent. 

The converted double-precision floating point value. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


atoi 

ANSI 

♦include <stdlib.h> 
int atoi(char *nptr) 

atoi () converts the string to which nptr to its integer equivalent. 
The converted integer value. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


atol 

ANSI 

#include <stdlib.h> 
long int atol(char *nptr) 

atol () converts the string to which nptr points to its long integer 
equivalent. 

The converted long integer value. 
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bsearch 

LIBRARY ANSI 

SYNTAX #include <stdlib.h> 

void *bsearch(void *key, 
void *base, 
size_t nmemb, 
size_t size, 

int (*compar) (void *, void *)); 

DESCRIPTION This performs a binary search of a sorted table. 

bsearch () calls the comparison function that compar points to with 

two arguments. The arguments point to the key object and to an array 
element, in that order. 

The comparison function returns an integer as follows: 

• less than zero, if the key object is less than the array element. 

• zero, if the key object is equal to the array element. 

• greater than zero, if the key object is greater than the array element. 

It’s good practice to make sure the array is sorted before passing it to 
bsearch(). 

These are the arguments tobsearch(): 

key Points to the object that bsearch will try to match, 

base Initial element of the array, 

nmemb Number of objects in the array, 

size Size of each element in the array, 

compar () Pointer to the comparison function. 

RETURNS A pointer to the element of the array that matches the key, if it finds a 

match. 

NULL, if it doesn’t find a match. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


calloc 

ANSI 

#include <stdlib.h> 

void *calloc(size_t nmemb, size_t size); 

calloc () allocates space for an array of nmemb objects, each of whose 
size is size. It initializes all bits in the space to zero. 

Use free () to deallocate a block of memory that was allocated by 
calloc (). 

A pointer to the allocated space, if successful. 

NULL, if failure. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ceil 

ANSI 

♦include <math.h> 
double ceil(double x); 

ceil () rounds x up to the next highest integer. For example, 
ceil (1.1) is 2, and ceil (4.9) is 5. 

A double that is the next highest integer from x. 
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clcarcrr 


LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


ANSI 

#include <stdio> 

void clearerr(FILE ‘stream); 

clearerr () clears the end-of-file and error indicators for the stream 
that stream points to. 

terror (), feof(), rewind() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


clock 

ANSI 

#include <time.h> 
clock_t clock(void) 

clock () determines the elapsed time since power-up, in clock ticks. 

The time in seconds is clock () / CLOCKS_PER_SEC. 

clock () is useful for calculating durations. 

The elapsed time since power-up, in clock ticks, if successful 

(clock_t) -1, if that time is not available or its value cannot be 
represented. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


COS 

ANSI 

#include <math.h> 
double cos(double x); 

cos () computes the cosine of the argument x. 

cos x, in radians. 
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cosh 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ANSI 

#include <math.h> 
double cosh(double x); 

cosh () computes the hyperbolic cosine of the argument x. 
cosh x, in radians, if successful, 

Infinity, if x is too large. It also sets errno to ERANGE. 


46 



ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ctime 

ANSI 

#include <time.h> 

char *ctime (time_t *timer); 

ctime () converts to local time the calendar time timer points to. The 
result is a 26-character string in the form (for example): 

Sun Sep 16 01:03:52 1973\n\0 

ctime () is equivalent to asctime (localtime (timer) ). 

If timer is NULL, ctime () takes the time from the Macintosh’s time 
buffer. 

A pointer to the string containing the local time. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


difftime 

ANSI 

#include <time.h> 

double difftime(time_t timel, time_t timeO); 

difftime () computes the difference between two calendar times, 
timel-timeO. 

The difference between two calendar times, in seconds, as a double. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


div 

ANSI 

#include <stdlib.h> 

div_t div(int numer, int denom) 

div () computes the quotient and remainder of the division of the 
numerator numer by the denominator denom; that is: 

quot * denom + rem == numer. 

If the division is inexact, the resulting quotient is the integer of lesser 
magnitude that is the nearest to the algebraic quotient. 

This returns a function of type div_t, which looks like this: 

struct { 

int quot; /* quotient */ 
int rem; /* remainder */ 

} 

A structure of type div_t that contains the results of the division. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


exit 

ANSI 

#include<stdlib.h> 
void exit (int status); 

exit () terminates the program normally. 

exit () executes all functions registered with _atexit () or 
atexit (), flushes all open output streams, closes all open files, and 
removes all temporary files. 

The status argument is ignored. 

_exit (),abort () 
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LIBRARY 


exp 

ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <math.h> 
double exp(double x); 

exp () computes e (the base of natural logarithms) to the xth power. 
e x , if successful 

Infinity, if the argument is too large for a double-precision floating point 
number. It also sets errno to ERANGE. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


fabs 

ANSI 

#include <math.h> 
double fabs(double x); 

fabs () computes the absolute value of a floating-point number, x. 
I x I, for any value x. 


52 




ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


fclose 

ANSI 

#include <stdio.h> 

int fclose(FILE *stream); 

f close () flushes the stream that stream points to and closes the file 
that is associated with that stream, f close () delivers any unwritten 
buffered data to the host environment and discards any unread buffered 
data. 

fclose () won’t close or deallocate buffers that the program allocated 
itself (e.g., by handing a buffer to setbuf () ) but it will close buffers that 
were allocated automatically (e.g., by setbuf (), if the program called 
setbuf () but did not hand it a buffer, or by f open () ). 

The difference between fclose () and the Unix Library function 
close () is that fclose () takes a file pointer as its argument, while 
close () takes a file descriptor number. 

0 (zero), if successful. 

EOF, if failure. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


feof 

ANSI 

#include <stdio> 

int feof (FILE *stream) ; 

feof () tests the end-of-file indicator for the stream that stream points 
to. 

feof () is useful to test when a previous I/O call to the given stream 
caused an EOF error (such as trying to get a character after having 
reached the end of the file). 

Note: If you use clearer r () to clear the error flag of a stream, 
feof () will no longer report an EOF error. Similarly, a later call 
with another type of error will also erase the EOF error flag. 

(f seek () clears the EOF indicator.) 

Non-zero, if at the end of the file. 

Zero, otherwise. 


54 



ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


ferror 

ANSI 

#include <stdio.h> 

int ferror (FILE *stream); 

ferror () tests the error indicator for the stream that stream points to. 

To clear the error, use clearerror (). (rewind () clears the error 
indicator for a stream automatically.) 

Non-zero, if the stream’s error indicator is set. 

Zero, otherwise. 

feof(),clearerr(), rewind() 
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SYNTAX 

DESCRIPTION 


RETURNS 


fflush 

ANSI 

#include <stdio.h> 
int fflush(FILE *stream) 

f flush () flushes the I/O buffer of the given stream, f flush () allows 
the program to switch cleanly between reading and writing on the same 
stream. 

For streams on which the program was just writing, f flush () causes 
any unwritten data for the stream to be delivered to the host environment. 

For streams on which the program was just reading, f flush () discards 
any unread data in the buffers associated with the stream. 

If stream is a NULL pointer, f flush () flushes all streams on which 
there is still unwritten data, that is, on all write streams. 

0 (zero), if successful. 

EOF, if an error occurred while trying to flush the buffer. 
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DESCRIPTION 


RETURNS 

SEE ALSO 


fgetc 

ANSI 

#include <stdio.n> 

int fgetc(FILE *stream); 

fgetc () reads in the next character from the given stream. 

fgetc () returns an unsigned integer in the range 0 - 255 (decimal), or 
EOF. 

Since fgetc () returns the integer value of the character, it is useful for 
getting bytes from binary files. 

To read in multiple characters more efficiently, you can also use 
f read () or fgets (). To read text and data directly into variables, use 
scanf (). 

The next character from the input stream, if successful. 

EOF, if failure. Also, it sets file’s error indicator if there was a read error, 
and sets the file’s EOF indicator if it reaches the end of the file. 

fread(), fgets (), fscanf(),getc(),gets (),read(), scanf () 
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SYNTAX 

DESCRIPTION 

RETURNS 


fgctpos 

ANSI 

#include <stdio.h> 

int fgetpos (FILE *stream, fpos_t *pos); 

f getpos () stores in the object that pos points to the current value of 
the file position indicator for the stream that stream points to. 

Zero, if successful. 

Non-zero, if failure. It also stores a positive value inerrno. 
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RETURNS 


fgets 

ANSI 

♦include <stdio.h> 

char *fgets(char *s, int n, FILE ‘stream); 

fgets () tries to read the next n-1 characters from the given stream into 
the array s. 

fgets () stops reading after it encounters a new-line character or after 
EOF, stores the new-line followed by a NULL character into s, and returns 
successful. 

fgets () writes a NULL character immediately after the last character it 
writes to s. 

s, if successful. 

NULL, if failure. If it encounters an EOF and has not read any characters, it 
doesn’t change the contents of s and sets the EOF error flag in the file 
descriptor. If a read error occurs, the contents of s are indeterminate. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


floor 

ANSI 

#include <math.h> 
double floor(double x); 

f loor () rounds x down to the next lowest integer. In other words, 
floor () computes the largest integral value not larger than x. For 
example, floor (1.1) is 1.0, and floor (4.9) is 4.0 . 

The largest integral value not larger than x, as a double 
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RETURNS 


fmod 

ANSI 

#include <math.h> 

double fmod(double x, double y); 

fmod () computes the floating point remainder of x/y. 

The remainder of x/y with the same sign as x, as a double, if successful 
0 (zero), if y is zero. It also sets err no to EDOM. 
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fopen 

LIBRARY ANSI 

SYNTAX #include <stdio.h> 

FILE *fopen(char *filename, char *mode); 

DESCRIFTION fopen () opens the given file, fopen () automatically allocates a buffer 

for the file’s stream, creates a new stream, and sets the stream to be fully- 
buffered. fopen () clears the error and EOF indicators for the stream. 

These are the arguments to fopen (): 

f i 1 ename pointer to the name of the file. 

mode pointer to a string describing how to open the file. 

The three main modes are read, write, and append. Each mode has a 
similar set of variations: read binary, write binary, append binary, and so 
on. 

These are all the possible modes: 

String Mode 

r Open this text file for reading. 

w Truncate this text file to zero length, or create a new text 

file for writing. 

a Append to this file. That is, open or create this text file 

for writing at end-of-file. 

rb Open this binary file for reading. 

wb Truncate this binary file to zero length, or create a new 

binary file for writing. 

ab Append to this binary file. That is, open or create this 

binary file for writing at end-of-file. 

r+ Open this text file for updating (reading and writing). 

w+ Truncate this text file to zero length or create a new text 

file for updating (reading and writing). 

a+ Open this text file for updating (reading and writing), but 

append all writing at the end of the file, 
r+b or rb+ Open this binary file for updating (reading and writing). 

w+b or wb+ Truncate this binary file to zero length or create a new 

binary file for updating. 
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RETURNS 


SEE ALSO 


a+b or ab+ Open this binary file for updating (reading and writing), 
but append all writing at the end of the file. 

When opening a file for reading (i.e., mode is r, rb, r+, or r+b/rb+) and 
there is no file named filename, fopen () fails and returns NULL. 

When opening a file for appending (i.e., mode is a, ab, a+, a+b, or ab+), 
all writing is appended to the end of the file, regardless of intervening 
calls to f seek (). 

When opening a file for updating (i.e., + is the second or third character 
in mode), the program can both read from and write to the associated 
stream. However, between a read and a write (or vice versa), the program 
must make an intervening call to f flush () or one of the file positioning 
functions (f seek (), f setpos (), or rewind () ). 

A pointer to the stream, if successful 

NULL, if failure. 

open (),fileno(), fclose(), fflush(), fread(), fwrite(). 
f reopen () opens a file on a specific stream. 
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DESCRIPTION 


RETURNS 

SEE ALSO 


fprintf 

ANSI 

#include <stdio.h> 

int fprintf(FILE *stream, char *format, ...) 

fprintf () writes to the given stream. It takes the output from the data 
arguments, converts them according to the format specifiers in the format 
argument, and writes the result to the stream that stream points to. 

These are the arguments to fprintf (): 
stream The stream fprintf () writes to. 

f o rmat Pointer to a string of format specifiers. 

Represents the list of data that fprintf ( ) writes. 

For complete information on format specifiers, read the “printfO / scanfO” 
appendix 

The data f printf () prints must consist of valid expressions 
The number of characters printed, if successful. 

A negative value, if failure. 

fscanf(),printf(), scanfO , sprintf(), sscanf(), 
vfprintf (),vprintf(), vsprintf() 
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RETURNS 

SEE ALSO 


fputc 

ANSI 

♦include <stdio.h> 

int fputc(int c, FILE *stream); 

fputc () adds a single character c to the output stream stream. 

fputc () writes the character at the position indicated by the file position 
indicator that is associated with the stream. It then advances the indicator 
appropriately. 

If the file cannot support positioning requests, or if the stream was 
opened with append mode (see f open ()), fputc () appends the 
character to the end of the output stream. 

The integer value of the character c, if successful 

EOF, if failure (e.g., file is read only). 

putc (), fputs(),fwrite (), fprintf (). 
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SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


#include <stdio> 

int fputs(char *s, FILE *stream); 

fputs () writes the string to which s points to the stream to which 
stream points. 

The string must end in a NULL (' \0 '), but fputs () does not write the 
NULL to the stream. 

0 (zero), if successful. 

EOF, if failure 

puts (), fprintf (),fwrite(), fputc (). 
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RETURNS 


fread 

ANSI 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nmemb, 
FILE ^stream); 

fread () reads items from the given stream and stores them in a block of 
memory. 

fread () advances the file position indicator for the stream according to 
the number of characters it successfully reads. 

If fread () reaches the end of the file before it has read the specified 
number of items, it sets the stream’s EOF indicator and returns the 
number of items it was able to read. 

These are the arguments to fread (): 

ptr Pointer to the area of memory into which fread () will 

store what it reads. 

size Size (uniform) of the items that fread () should read, 

nmemb Number of items that f read () should read, 

stream Stream from which fread () should read the items. 

The number of items successfully read and stored, if successful. 

The number of items successfully read and stored, if failure (e.g., read 
error) or end-of-file. 

0 (zero), if size or nmemb is 0 (zero). But the contents of the area of 
memory into which it was supposed to read and the state of the stream 
remain unchanged. 
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SEE ALSO 


free 

ANSI 

#include <stdlib.h> 
void free(void *ptr); 

f ree () releases the block of memory that pt r points to, making the 
memory available for further allocation. 

Note: Make sure the argument free () receives is a pointer 
returned earlier by calloc (), malloc (), or realloc (), 
Otherwise, the results are unpredictable. 

free () keeps its own internal accounting of how much memory to free. 

If pt r is a NULL pointer, free () performs no action. 

calloc (), malloc (), cf ree (). 
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freopen 

ANSI 

#include <stdio.h> 

FILE *freopen(char *filename, char *mode, 

FILE *stream); 

freopen () opens a file using a specific stream, as opposed to 
f open (), which opens a file on a new stream. 

freopen () first tries to close any file that is associated with the stream 
stream. 

If freopen () fails to close such a file successfully, it ignores the failure. 

f reopen () then opens the given file whose name is in the string that 
filename points to, and associates the stream stream with that file. 

f reopen () then clears the stream’s error and EOF indicators. 

The value of stream, if successful. 

NULL, if the open fails. 

f open (), f close (), f reopenc () (in the console library). 
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RETURNS 

SEE ALSO 


frexp 

ANSI 

#include <math.h> 

double frexp(double value, int *exp); 

frexp () breaks the floating-point number value into a normalized 
fraction (the mantissa) and an integral power of two (the exponent), so 
that 

mantissa * 2 (exponent) == value. 

frexp () stores the exponent in *exp, and it returns the mantissa. 

The mantissa is in the range 0.5 to 1 (or zero, if there’s an error). 

The mantissa. If value is 0 (zero), both the mantissa and the exponent will 
be zero. 

ldexp (), the inverse function of frexp (). 
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fscanf 

ANSI 

#include <stdio.h> 

int fscanf(FILE *stream, char *format, ...); 

fscanf () reads from the given stream. It separates the input according 
to the format specifiers in the format argument and stores the results in 
the objects pointed to by the data arguments. 

fscanf () is the input analog of f print f (). If the format is exhausted 
while arguments remain, fscanf () will evaluate the excess arguments 
but will otherwise ignore them. 

These are the arguments to fscanf (): 

stream The stream from which f scanf () should read, 

format Pointer to a string of format specifiers. 

Represents the items into which fscanf () will store the 
data it reads. These items must all be pointers. 

For complete information on format specifiers for fscanf (), read the 
appendix on “printfO / scanfO.” 

The number of items successfully assigned, if successful. This can be 
fewer than the number of items in its argument list or even zero in the 
event of an early matching failure (i.e., when an input argument does not 
match what fscanf () is looking for). 

EOF, if an input failure occurs before it performs any data conversion. 

fprintf (),printf(),scanf(), sprintf(), sscanf(), 
vfprintf (),vprintf() , vsprintf() 
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fseek 

ANSI 

include <stdio.h> 

int fseek(FILE *stream, long int offset, 
int whence); 

f seek () sets the file position indicator for the given stream. (The file 
position indicator measures the position in characters from the beginning 
of the file.) 

When fseek () is successful, it clears the stream’s EOF indicator and 
undoes any effects of ungetc () on the same stream. 

fseek () is useful for performing nonsequential I/O to a file, since it lets 
the program manipulate the file position indicator itself rather than having 
to follow the indicator, which is set automatically by other I/O calls, 
through the file. 

These are the arguments to f seek ( ) : 
stream The file in which to seek. 

offset The amount of space in the file through which to seek, 

whence The position from which to start seeking. 

These macros are useful values for whence: 

SEEK_SET The beginning of the file. 

SEEK_CUR The current value of the file position indicator. 
SEEK_END The end of the file. 

For a binary stream, the new position will be of f set + whence. 

For a text stream, one of these must be true: 

• offset is zero 

• of f set is a value returned by ft ell () (on the same stream) and 
whence is SEEK_SET. 

Zero, if successful. 

Non-zero, if failure. 

lseek() (in the Unix library). 
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fsetpos 

ANSI 

#include <stdio.h> 

int fsetpos (FILE ‘stream, fpos_t *pos); 

fsetpos () sets the file position indicator for the file that stream points 
to according to the setting of pos. 

pos must be a value from an earlier call to f get pos () (on the same 
stream). 

A successful call to fsetpos () clears the EOF indicator for the stream 
and undoes any effects of ungetc () on the stream. After an fsetpos () 
call, the next operation on an update stream may be either read or write. 

Zero, if successful. 

Non-zero, if failure. It also stores a positive value in errno. 
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ftell 

ANSI 

#include <stdio.h> 

long int ftell (FILE *stream); 

f tell () obtains the current value of the file position indicator for the 
given stream. 

The f seek () function can use this value to return the indicator to its 
position at the time of the f tell () call. 

The current value of the file position indicator for stream, if successful. 
-1L, if failure. It also stores a positive value in errno. 
tell () (in the Unix library), f seek () 
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fwrite 

ANSI 

#include <stdio.h> 

size_t fwrite(void *ptr, size_t size, 

size_t nmemb, FILE ‘stream) ; 

fwrite () writes a block of data to stream. 

These are the arguments to f write (): 
ptr Pointer to the memory to write to. 

size Size (uniform) of the items to write, 

nmemb Number of items to write, 

stream Stream to write to. 

If f seek ( ) has set the stream’s file position indicator, fwrite ( ) will 
advance the indicator by the number of characters fwrite () has 
successfully written. 

The number of items successfully written, if successful. 

The number of items successfully written before the failure, if failure, 
fread(), write(), fprintf(), fputs(),fputc (),putc(). 
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getc 

ANSI 

♦include <stdio.h> 
int getc(FILE *stream) 

getc () is a macro that calls f getc (). 

Note: Since getc () is a macro and not a function, it may 
evaluate stream more than once. Make sure stream is not an 
expression that can have side effects. 

The integer value of the next character from stream, if successful. 

EOF, on error or end-of-file. 
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LIBRARY 


getchar 

ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <stdio> 
int getchar(void) 

getchar () is a macro that calls fgetc (), supplying stdin as the 
argument. This gets the next character from the standard input. 

The integer value of the character, if successful. 

EOF, if error or end-of-file. 


77 



Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


getenv 

ANSI 

#include <stdio.h> 
char *getenv(char *name); 

getenv () is provided for ANSI and Unix compatibility. It always returns 
NULL. 

NULL 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


gmtime 

ANSI 

#include <time.h> 

struct tm *gmtime (time_t *timer); 

gmtime () is provided for ANSI and Unix compatibility. It always returns 
NULL. 

NULL 
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isxxxx 

SYNTAX #include <ctype.h> 

int isxxx(int c); 

DESCRIPTION isxxx () represents a family of functions that perform various tests on a 

character. These functions all work the same way: the program passes the 
function a single character as an argument, which the function tests. The 
function returns 0 (true) or non-zero (false) depending on whether the 
character c passes the test 

Function Test 

isalnum(c) Is c an alphanumeric character? (a— z, A— Z, 0—9) 
isalpha (c) Is c an alphabetic character? (a—z, A— Z) 

iscntrl (c) Is c a control character? (ASCII codes 0—IF inclusive and 
7F, hexadecimal) 

i sdigit (c) Is c a decimal digit? (0—9) 

i sgraph (c) Is c a printing character (but not a space (' 1 ))? (ASCII 

codes 21—7E inclusive, hexadecimal) 

is lower (c) Is c a lowercase character? (a—z) 

isprint (c) Isca printing character, including space (' ')? (ASCII 

codes 2 0—7E inclusive but not 7F, hexadecimal) 

ispunct (c) Is c a printing character that is neither space (' ') nor a 

character for which isalnum () is true? 

These are the punctuation characters : 

#$%*() \ ~ \ I 

[ ] { 1 - _ = + 

isspace(c) Isca standard white-space character? 

These are the whitespace characters: 

space (' ') 

form feed (' \ f') 

new-line (' \ n') 

carriage return (' \ r') 

horizontal tab (' \ t') 

vertical tab (' \ v') 

is upper (c) Is c an uppercase character? (A—Z) 
isxdigit (c) Is c a hexadecimal digit? (0—9, A—F, a—f) 
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RETURNS 


Non-zero, if the condition is true 
Zero, if the condition is false. 


! 


i 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


labs 

ANSI 

♦include <math.h> 

long int labs(long int j); 

labs () computes the absolute value of its long integer argument j. 
I j I for any integer j, as a long integer. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 
SEE ALSO 


ldexp 

ANSI 

♦include <math.h> 

double ldexp(double x, int exp); 

ldexp () multiplies the floating point number x by the integral power 
exp of 2. 

x * 2 ex P 

f rexp (), the inverse function of ldexp (). 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


ldiv 

ANSI 

#include <stdlib.h> 

ldiv_t ldiv(long int numer, long int denom); 

ldiv () is similar to div () except that the arguments and the members 
of the structure that is returned all have type long int. 

It returns a structure of type ldiv_t, which looks like this: 

struct { 

long int quot; /* quotient */ 
long int rem; /* remainder */ 

} 


A structure containing the results of the division. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


localeconv 

ANSI 

#include <locale.h> 

struct lconv *localeconv(void); 

localeconv () is provided for ANSI C compatibility only. THINK C 
supports only the minimal locale environment. According to the standard, 
localeconv () returns an object of type struct lconv, with values 
appropriate for the formatting of numeric quantities (monetary and 
otherwise) according to the rules of the current locale. 

In THINK C, localeconv () returns values for the "C" locale, the 
minimal environment. 

A pointer to an object of type struct lconv. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


localtime 

ANSI 

#include <time.h> 

struct tm *localtime(time_t *timer); 

local time () converts the calendar time that timer points to to a 
broken-down time, expressed as local time. 

A pointer to the broken-down time. 


86 




ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


log 

ANSI 

♦include <math.h> 
double log(double x) 

log () computes the natural logarithm of x. 

In x (the natural logarithm of x), if x is greater than 0 (zero). 

Negative infinity, if x is zero or negative. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


loglO 

ANSI 

#include <math.h> 
double loglO(double x) 

log 10 () computes the base-10 logarithm of x. 

log x (the base-10 logarithm of x), if x is greater than 0 (zero). 

Negative infinity, if x is zero or negative. 


88 



ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


longjmp 

ANSI 

♦include <setjmp.h> 

void longjmp(jmp_buf env, int val); 

long jmp () together with set jmp () lets you do a non-local goto. 

longjmp () bypasses the usual function call and return mechanisms, and 
jumps directly back to the point established by a set jmp () call, 
set jmp () sets up the buffer that longjmp () specifies in the env 
argument. 

longjmp () restores the environment that was saved by the most recent 
call to set jmp (). 

Don’t use longjmp () if you haven’t previously called set jmp () or if 
you called set jmp () in a function that has terminated execution. 

When longjmp () is called, all accessible objects have values, but some 
values are indeterminate. An object will have an indeterminate value only 
if it satisfies these qualifications : 

• It is of automatic storage duration. 

• It is local to the function that contains the corresponding set jmp () 
call. 

• It was changed between the call to set jmp () and the call to 
longjmp(). 

val 

(After longjmp () completes, the program continues executing as if the 
corresponding call to set jmp () had just returned val. The only 
exception is that since set jmp () uses 0 (zero) to denote a true return, if 
val = 0, set jmp () converts 0 to 1 and returns 1, to continue to 
consistently denote that the return is from longjmp ().) 


SEE ALSO 


setjmp() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


malloc 

ANSI 

♦include <stdlib.h> 
void *malloc(size_t size); 

malloc () allocates a block of memory for an object, size specifies the 
size of the object. 

Unlike calloc(),malloc() does not clear the block of memory. 

To free the memory that malloc () allocates, use free () . 

A pointer to the block of space, if successful. 

NULL, if failure 

free() , calloc () , realloc (). 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


mblen 

ANSI 

#include <stdlib.h> 

int mblen(char *s, size_t n) ; 

mblen () is provided for ANSI C compatibility only. THINK C does not 
support multi-byte characters. According to the standard, mblen () 
determines the number of bytes comprising the multi-byte character s 
points to. 

In THINK C, mblen () returns 0 if s is NULL; 1, otherwise. 

1, if s is not NULL. 

0, if s is NULL 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 
SEE ALSO 


mbstowcs 

ANSI 

♦include <stdlib.h> 

size_t mbstowcs(wchar_t *pwcs, char *s, 
size_t n); 

mbstowcs () is provided for ANSI C compatibility only. THINK C does 
not support multi-byte characters. According to the standard, 
mbstowcs () converts a multi-byte character to which s points to a 
sequence of codes, stores it in the array pews points to, and returns the 
number of array elements changed. 

In THINK C, westombs () simply copies the elements of s to pews, 
stopping after it copies n elements or a NULL character. 

The number of characters copied. 

mblen (),westombs() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


mbtowc 

ANSI 

#include <stdlib.h> 

int mbtowc(wchar_t *pwc, char *s, size_t n); 

mbtowc () is provided for ANSI C compatibility only. THINK C does not 
support multi-byte characters. According to the standard, mbtowc () 
converts the multi-byte character to which s points to a code (converting 
no more than n bytes), stores the code in the object pwc points to, and 
returns the length in bytes of the multi-byte character. 

In THINK C, wctomb () sets wchar to the first element of s, if s is not 
NULL, and n is not 0. 

1, if successful. 

0, if s is NULL. 

-1, if n is 0. 

mblen () , wctomb () 
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LIBRARY 


memchr 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


♦include <string.h> 

void *memchr(void *s, int c, size_t n); 

memchr () locates the first occurrence of c in the initial n characters of 
the object that s points to. 

The program should make sure that c is in the range 0 - 255 inclusive, 
decimal. 

A pointer to the located character, if it finds the character. 

NULL, if it doesn’t find the character. 
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LIBRARY 


memcmp 

ANSI 


SYNTAX 


DESCRIPTION 

RETURNS 


♦include <string.h> 
int memcmp(void *sl, void *s2, 
size_t n); 


memcmp () compares the first n characters of the object that si points to 
to the first n characters of the object that s2. 


a positive integer 
zero 

a negative integer 


if si’s object is greater in value than s2’s. 

if si’s object is equal to s2’s. 

if si’s object is less in value than s2’s. 
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LIBRARY 


memcpy 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


♦include <string.h> 

void *memcpy(void *sl, void *s2, size_t n); 

memcpy () copies n characters from the object that s2 points to into the 
object that s 1 points to. 

The program must make sure that si and s2 do not overlap. If they 
might overlap, the program should use memmove () instead. 

The value of si. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


memmove 

ANSI 

♦include <string.h> 

void *memmove(void *sl, void *s2, size_t n); 

memmove () copies n character from the object that s2 points to into the 
object that s 1 points to. 

memmove () works correctly even if si and s2 overlap. 

The value of s 1. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


memset 

ANSI 

♦include <string.h> 

void *memset(void *s, int c, size_t n); 

memset () copies the value of c into each of the first n characters of the 
object that s points to. 

memset () coverts c to an unsigned char to perform the copying, 
memset () returns the value of s. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


mktime 

ANSI 

♦include <time.h> 

time_t mktime(struct tm *timeptr); 

mktime () converts a broken-down time into a calendar time. (To 
convert a calendar time into a broken-down time, use ctime ().) 

This calendar time has the same encoding as that of the values that 
time() returns. 

mktime () ignores the original values of the tm_wday and tm_yday 
components of the structure. The original values of the other components 
are not restricted to the ranges indicated 

On successful completion, mktime () sets the values of the tm_wday 
and tm_yday components, and sets the other components to represent 
the specified calendar time, but it forces their values to the ranges 
indicated 

mktime () does not set the final value of tm_mday until it determines 
tm_mon and tm_year. 

The calendar time encoded as a value of type time_t, if successful 
(time_t) -1, if the calendar time cannot be represented. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


modf 

ANSI 

#include <math.h> 

double modf(double x, double *ip); 

modf () splits x into integral and fractional parts; both parts carry the 
same sign as x. modf () stores the integral part in * ip and returns the 
signed fractional part. 

The signed fractional part of x. 
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LIBRARY 


perror 

ANSI 


SYNTAX 

DESCRIPTION 


#include <stdio.h> 
void perror(char *s); 

perror () maps the error number in errno to string and prints an error 
message. 

perror () writes this to stderr: 
user String: errorMessage 

where user String is the argument s and errorMessage is an error message 
string appropriate for the error number in errno. 

The content of the error message string is the same as the one 
strerror () returns when the program hands strerror () errno. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


pow 

ANSI 

#include <math.h> 

double pow(double x, double y); 

pow () computes x¥, x raised to the power of y. 

x^, if x is greater than zero 

Negative infinity, if x is zero and y is less than or equal to zero, or if x is 
negative and y is non-integral. It also sets errno to EDOM. 

Infinity with the same sign as x, if the result is too large to represent. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


printf 

ANSI 

♦include <stdio.h> 

int printf(char *format, ...); 

printf () performs the same operations as fprintf () except that 
printf () writes its output to stdout. 

For complete information on the format specifier arguments, read the 
“printfO / scanfO” appendix. 

The number of characters it wrote to stdout, if successful 
A negative value, if failure, 
fprintf (), fscanf () , scanf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


putc 

ANSI 

#include <stdio.h> 

int putc(char c, FILE *stream) ; 

putc () writes a character to the output stream. 

putc () is similar to f putc () except that putc () is a macro and not a 
true function. 

Note: Since putc () is a macro, it may evaluate stream more 
than once. Make sure the stream argument is not an expression 
that can have side effects. 

The integer value of the character, if successful. 

EOF, if failure. It also sets the error indicator for the stream. 

fputc (),getc(), fgetc() 
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LIBRARY 


putchar 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


♦include <stdio.h> 
int putchar(int c) ; 

putchar () calls the fput () function, supplying stdout as the output 
stream. 

putchar () is implemented as a macro rather than a true function. 

The character written, if successful. 

EOF, if failure. It also sets the error indicator for the stream, 
putc (),puts(),printf() 
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LIBRARY 


puts 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


#include <stdio.h> 
int puts(char *s) ; 

puts () writes the given string to stdout, appending a newline (' \n') 
character to the output. 

s points to the string. The string must have a NULL character as a ter¬ 
minator; but puts () does not write this terminator to the output. 

0 (zero), if successful 

EOF, if failure 

fputs (),printf(), putchar(). 
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LIBRARY 

SYNTAX 

DESCRIPTION 


qsort 

ANSI 

#include <stdlib.h> 

void qsort(void *base, size_t nmemb, size_t size, 
int (*compar) (void *, void *) ) ; 

qsort () sorts an array in ascending order according to the results of a 
comparison function. 

These are the arguments to qsort (): 

base Pointer to the initial element of the array. 

nmemb Number of elements in the array. 

size Size of each element in the array. 

compar The comparison function, which takes two arguments. 

The arguments should be pointers to the objects it 
compares. 

The comparison function returns an integer less than, equal to, or greater 
than zero according to whether it considers the first object less than, equal 
to, or greater than the second argument, respectively. 
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raise 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


#include <signal.h> 
int raise(int sig); 

raise () sends the signal sig. 

The signal-handling software then processes the signal according to the 
settings of the program’s most recent call to signal (). 

signal () can specify that the signal-handling software ignore the signal, 
use default signal handling, or dispatch to a specific (e.g., user-written) 
signal-handling routine. 

For more information on signal-handling, see the section on signal (). 
Zero, if successful. 

Non-zero, if failure. 

signal (), kill () (in the Unix library) 
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SYNTAX 

DESCRIPTION 

RETURNS 
SEE ALSO 


ANSI 3 


rand 

ANSI 

#include <stdlib.h> 
int rand(void); 

rand () returns a pseudo-random integer in the range 0 to RAND_MAX. 

Successive calls to rand () result in a pseudo-random sequence of 
numbers. 

If you set the seed (using srand ()) to the same number each time you 
run your program, you’ll always get the same sequence of pseudo¬ 
random numbers. 

A pseudo-random integer in the range 0 to RAND_MAX. 
srand(). 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 

SEE ALSO 


realloc 

ANSI 

#include <stdlib.h> 

void *realloc(void *ptr, size_t size); 

realloc () changes the size of a given memory region while preserving 
the region’s contents. If necessary, realloc () copies the contents to 
another region of memory. 

realloc () is useful when the program needs a larger size specification 
(e.g., long rather than int). 

These are the arguments to realloc (): 

ptr A pointer that was returned earlier by a call to 

calloc (), malloc (), or realloc (). 
size The desired new size of the memory region. 

Note: If ptr points to space that has been deallocated (e.g., it 
matches a pointer that was returned by a call to free () or 
realloc ()), the behavior of realloc () is undefined. 

realloc () handles these special cases: 

• If ptr is NULL, realloc () behaves like a call to malloc () for the 
specified size. 

• If the new size is smaller than the old size, realloc () takes away 
space at the end of the old region and discards the contents of that 
space. 

• IfsizeisO (zero) and ptr is not NULL, realloc () frees the region 
that ptr points to. 

• If the new size cannot be allocated, realloc () leaves the region 
unchanged and returns NULL. 

A pointer to the new memory space, if successful. 

NULL, if failure. 

malloc(). 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


remove 

ANSI 

#include <stdio.h> 

int remove(char *filename); 

remove () deletes a file. 

If the file is open, remove () returns nonzero and the file remains 
unchanged. 

Zero, if successful. 

Non-zero, if failure. 
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rename 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <stdio.h> 

int rename(char *old, char *new); 

rename () changes the name of a file from the string that old points to 
to the string that new points to. 

Zero, if successful. 

Non-zero, if failure. If the file existed previously, its name remains 
unchanged. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


rewind 

ANSI 

#include <stdio.h> 

void rewind(FILE *stream); 

rewind () sets the file position indicator for given stream to the be¬ 
ginning of the file. 

Remember that this indicator is moved automatically during I/O and it is 
moved explicitly by f seek (). 

rewind () also clears the error indicator for the stream, 
fseek (),lseek() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


scanf 

ANSI 

#include <stdio.h> 

int scanf(char *format, ...); 

scanf () performs the same operations as f scanf () except that 
scanf () uses stdin as the input stream. 

For complete information on format specifiers, read the appendix on 
“printfO / scanfO.” 

The number of items successfully read, if successful. This can be fewer 
than the number of items in the argument list or even zero in the event of 
an early matching failure, i.e., when an input argument does not match 
what scanf () is looking for. 

EOF, if an input failure occurs before any data conversion. 
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SYNTAX 

DESCRIPTION 


setbuf 

ANSI 

#include <stdio.h> 

void setbuf(FILE ‘stream, char *buf); 

Except that setbuf () returns no value, setbuf () is similar to 
setvbuf (), as follows: 

• When buf is not NULL, setbuf () is the same as calling setvbuf () 

with_ IOFBF for mode and BUFSIZ for size. 

• When buf is NULL, setbuf ( ) is the same as calling setvbuf () 
with IONBUF for mode. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 

SEE ALSO 


setjmp 

ANSI 

#include <setjmp.h> 
int setjmp(jmp_buf env); 

set jmp () together with long jmp () allows the program to do a non¬ 
local goto. This is useful for returning error information or other in¬ 
formation that might otherwise get lost. 

set jmp () establishes a destination to which a subsequent long jmp () 
call can jump. On this invocation of set jmp (), set jmp () returns 0 
(zero). 

long jmp () bypasses the usual function call and return mechanisms and 
jumps back to the point just after the set jmp () call as if set jmp () 
itself had just returned. On this return, set jmp () returns nonzero. 

Remember, set jmp () returns 0 (zero) on true return, non-zero on a 
return from a long jmp () call, long jmp () itself never returns; instead, 
execution proceeds as if the setjmp () call had returned. 

After a long jmp () occurs, variables in the function that called 
long jmp () are lost, and local non-static variables in the function that 
calls setjmp () are indeterminate 

set jmp () saves the environment in the array env, for use by 
longjmp(). 

Zero, if returning from a direct invocation. 

Non-zero, if returning from a call to long jmp (). 

1, if returning from a call a call to long jmp () with val = 0. 
longjmp() 


116 



ANSI 


3 


setlocale 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


#include<locale.h> 

char *setlocale(int category, char *locale); 

setlocale () is provided for ANSI C compatibility only. THINK C 
supports only the minimal "C" locale environment. 

In THINK C, setlocale () returns "C" if locale is either "C" or 
NULL. Otherwise, it returns NULL. 

"C", if locale is "C" or NULL. 

NULL, otherwise. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


setvbuf 

ANSI 

#include <stdio.h> 

int setvbuf(FILE *stream, char *buf, int mode, 
size_t size); 

setvbuf () lets the program specify how the given stream will be 
buffered, and it lets the program either supply a buffer or have 
setvbuf () automatically allocate a buffer. 

You should use setvbuf () after the stream that stream points to has 
been associated with an open file and before any other other operation is 
performed on that stream. 

These are the arguments to setvbuf (): 

mode One of the following values, describing how the stream 

will be buffered: 

_IOFBF Input/output will be fully buffered. 

_IOLBF Input/output will be line buffered. 

_IONBF Input/output will be unbuffered. 

buf Pointer to a buffer that the program supplies. If buf is 

NULL, setvbuf () allocates a buffer itself. 

size The size of the buffer that setvbuf () should allocate. 

If the file is a disk file, size should be a multiple of 512. 

Zero, if successful. 

Non-zero, if failure. If setvbuf () is called with an invalid value for 
mode, or if setvbuf () cannot allocate a buffer, or if the buffer that buf 
points to is too small, setvbuf () will not honor the request and will set 
mode to _IONBF (unbuffered). 
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DESCRIPTION 


signal 

ANSI 

#include <signal.h> 

void (*signal(int sig, void (*func) (int))) (int); 

signal () is part of the signal mechanism, which consists of signal () , 
raise (), kill (), and the underlying signal-handling software. The 
signal mechanism lets a program respond to external events and send 
messages to itself. 

Keep in mind that signals are not a balanced sender-receiver mechanism, 
despite the send-respond language used to describe them. 

To send a signal, call raise () or kill (). 

To specify the correct response to a signal, use signal (). signal () 
lets you specify ahead of time what the signal-handling software should 
do when a given signal occurs. You can change the response that 
signal () specifies many times before the signal occurs by simply 
calling signal () again with different values. 

Once the signal occurs, the signal-handling software performs the re¬ 
sponse specified by the last signal () call made. The software also 
resets this response to be the default response. 

After a given signal occurs, you must call signal () again in order to re¬ 
establish the non-default response for that signal. (You may leave the 
default setting as is if desired.) 

At program start-up, the signal software will initially ignore no signal and 
will perform the default response for all signals. 

Thereafter, signal () lets a program specify one of three responses — 
no response, default response, and user-defined response— as follows: 

• If the value of func is SIG_DFL, the signal-handling software will 
perform default handling of that signal (in THINK C, an abnormal 
program termination.) 
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• If f unc points to a function, the signal-handling software calls the 
function, using sig as the argument (and it resets f unc to be the 
default function thereafter). This called function executes normally, a 
typical task is to set a flag and then return. 

• If the value of func is SIG_IGN, the signal is ignored. 

These are the arguments to signal (): 

sig The signal number of the signal. Valid signals are listed 

in the next section. 

func The desired outcome for the given signal, func can be a 

pointer to a function or one of the following values: 

SIG_DFL Perform default handling of the signal. 

SI G_IGN Ignore the signal. 

If func is a pointer to a function, that function cannot 
call any library routines. 

pointer Call the function that this pointer points to when the 

signal sig occurs. 

Avoid the following situations: 

• func uses return, and the value of sig is SIG_FPE or any other 
implementation-defined value that corresponds to a computational 
exception. 

• The signal does not come from abort () or raise (), and either the 
signal handler calls any function in the standard library other than 
signal () or the signal handler refers to any object with static storage 
duration other than by assigning a value to a static storage duration 
variable of type sig_atomic_t. Furthermore, if such a call to 
signal () causes signal () to return unsuccessfully, the value of 
errno is indeterminate. 

RETURNS The value of func for the most recent call for the specified signal sig, if 

successful. 

SIG_ERR, if failure. It also stores a positive value in errno. 

SEE ALSO raise (), kill ( ) (in the Unix library) 
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DESCRIPTION 

RETURNS 

SEE ALSO 


sprintf 

ANSI 

#include <stdio.h> 

int sprintf(char *s, char *format, ...); 

sprintf () performs the same operations as fprintf () except that it 
writes its output to the string s points to, instead of a stream. 

sprintf () appends a NULL character to the end of the characters it 
writes. 

For complete information on format specifiers, read the appendix on 
“printfO / scanfO.” 

The number of characters written to s, not counting the terminating 
NULL. 

fprintf (), print f (), scanf (), sscanf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


srand 

ANSI 

#include <stdlib.h> 

void srand(unsigned int seed); 

srand () initializes the pseudo-random number generator, using its 
argument as a seed for a new sequence. 

Use rand () to produce a pseudo-random number. 

Using the same number as the seed for srand () will always produce the 
same sequence of numbers. 
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RETURNS 


sscanf 

ANSI 

#include <stdio.h> 

int sscanf(char *s, char *format, ...) 

sscanf () performs the same operations as f scanf () except that it 
reads its input from from the string that s points to, instead of a stream. 

Reaching the end of the string for sscanf () is the same as reaching the 
end of a file for f scanf (). 

For complete information on format specifiers for f scanf (), read the 
appendix on “printfO / scanfO.” 

The number of items read, if successful. This can be fewer than the 
number of items in the argument list or even zero in the event of an early 
matching failure, i.e., when an input argument does not match what 
scanf () is looking for. 

EOF, if an input failure occurs before data conversion. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


strcat 

ANSI 

♦include <string.h> 

char *strcat(char *sl, char *s2) 

strcat () appends a copy of the string that s2 points to to the end of 
the string that si points to. 

The initial character of s2 overwrites the NULL character at the end of si. 

Make sure there is enough space for string s2 in the character array after 
the end of the string si. 

The value of si, after s2 has been appended. 
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strchr 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


#include <string.h> 

char *strchr(char *s, int c); 

strchr () locates the first occurrence of c (which it converts to a char) 
in the string that s points to. 

strchr () considers the terminating NULL character to be part of the 
string s. 

A pointer to the first occurrence of c in the string s, if c is found. 

The NULL pointer, if c is not found, 
strrchr() 
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LIBRARY 


strcmp 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


#include <string.h> 

int strcmp(char *sl, char *s2); 


strcmp () compares the string that si points to to the string that s2 
points to. 

Note that if si is a substring of s2, strcmp () will return a number 
greater than zero because the last characters it compares will be the 
terminating NULL (' \0 *) character of si against some character in s2. 


Positive integer 
0 

Negative integer 


if si is greater than s2. 
if si equals s2. 
if si is less than s2. 
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DESCRIPTION 

RETURNS 


strcoll 


ANSI 


#include <string.h> 

int strcoll(char *sl, char *s2); 

strcollO is provided for ANSI C compatibility only. THINK C supports 
only the minimal locale environment According to the standard, 
strcoll () compares the string that si points to to the string that s2 
points to, interpreting both strings as appropriate to the the current locale. 

In THINK C, strcollO returns the value that strcmp () would return 
for the same strings. 


Positive integer 
0 

Negative integer 


if s 1 is greater than s 2. 
if si equals s2. 
if s 1 is less than s 2. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 
SEE ALSO 


strcpy 

ANSI 

♦include <string.h> 

char *strcpy(char *sl, char *s2) ; 

strcpy () copies the string that s2 points to (including the terminating 
NULL character (' \ 0 ')) into the array that si points to. 

The value of s 1. 
strncpy() 
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DESCRIPTION 

RETURNS 


strcspn 

ANSI 

#include <string.h> 

size_t strcspn(char *sl, char *s2); 

strcspn () computes the length of the maximum initial segment of the 
string that s 1 points to that consists entirely of characters that are not 
from the string that s2 points to. 

st rcspn () returns the length of the segment. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


strerror 

ANSI 

#include <string.h> 

char *strerror(int errnum); 

strerror () uses the error number errnum to find the appropriate 
error message. 

You should not be modify the string returned, but a subsequent call to the 
strerror () function may overwrite it. 

A pointer to the string that contains the error message. 


130 




ANSI 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 


strftime 

ANSI 


♦include <time.h> 

size_t strftime(char *s, size_t maxsize, 

char *format, struct tm *timeptr); 

strftime () formats and prints a time. 

If copying takes place between objects that overlap, the behavior is 
undefined. 


These are the arguments to strftime (): 

s Pointer to the array into which strftime () should 

write the formatted time. 


maxsize 

format 


timeptr 


Maximum number of characters that strftime () may 
place into the array s. 

A string of one or more conversion specifiers, which 
strftime () replaces with actual values. The table 
below lists valid format specifiers and the values to 
which strftime () converts them. 

Pointer to a structure that contains the time that 
strftime () should format and write. It’s the same one 
thatgmtimeO and localtime () return. 
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These are the specifiers for strftime ()'s format argument: 

Specifier Replaced with: 

%a The abbreviated weekday name. 

%A The full weekday name. 

%b The abbreviated month name. 

%B The full month name. 

%c The appropriate date and time representation. 

% d The day and month as a decimal number (Range: 01-31). 

%H The hour (24-hour clock), as decimal number (Range: 

00-23). 

%I The hour (12-hour clock), as a decimal number (Range: 

01 - 12 ). 

% j The day of the year, as a decimal number (Range: 001- 

366 ). 

%m The month, as a decimal number (Range: 01-12). 

%M The minute, as a decimal number (Range: 00-59). 

%P The AM/PM designation for a 12-hour clock. 

%S The second, as a decimal number (Range: 00-61). 

%U The week number of the year (with Sunday as the first 

day of week 1), as a decimal number (Range: 00-53). 

%w The weekday, as a decimal number (Range: 0 (Sunday) - 

6 ). 

%w The week number of the year (with Monday as the first 

day of week 1), as a decimal number (Range: 00-53). 

%x The locale’s appropriate date representation. 

%X The locale’s appropriate time representation. 

%y The year without century, as a decimal number (Range: 

00-99). 


%Y The year with century, as a decimal number. 

% z The time zone name or abbreviation, or by no characters 

if no time zone is determinable. 

%% % 


132 



ANSI 


RETURNS 


The number of characters that placed into the array s, not including the 
terminating NULL, if successful. 

0 (zero), if the string generated, including the terminating NULL, is longer 
than maxsize. Also, the contents of the array are indeterminate. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


strlen 

ANSI 

♦include <strings.h> 
size_t strlen(char *s) ; 

strlen () computes the length of the string that s points to. 

strlen () returns the number of characters that precede the terminating 
NULL character. 
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SYNTAX 

DESCRIPTION 


RETURNS 

SEE ALSO 


strncat 

ANSI 

#include <string.h> 

char *stmeat(char *sl, char *s2, size_t n) 

strncat () appends a copy of the string that s2 points to to the end of 
the string that si points to, until it has appended n characters or it has 
reached the end of string s 2. 

The initial character of s2 overwrites the NULL character at the end of si. 

If strncat () appends n characters without reaching the end of s2, 
strncat () will add a terminating NULL character (' \0 *). 

Make sure there is enough space for s2 in the character array after the 
end of the string si. 


The value of si, after appending the string s2. If n is negative or zero, it 
returns si unchanged. 

streat () 
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strncmp 

LIBRARY ANSI 

SYNTAX #include <string.h> 

int strncmp(char *sl, char *s2, size_t n); 

DESCRIPTION strncmp () compares the string that si points to to the string that s2 

points to, up to a limit of n characters. 

strncmp () does not compare characters that follow the NULL character. 

RETURNS Positive integer if the first n characters of s 1 are greater than 

the first n characters of s2. 

0 if the first n characters o f s 1 are equal to 

the first n characters of s2. 

Negative integer if the first n characters of si are less than 

the first n characters of s2. 

SEE ALSO s t rcmp () 
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strncpy 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


linclude <string.h> 

char *strncpy(char *sl, char *s2, size_t n); 

strncpy () copies characters from s2 to si until either it has copied n 
characters or it reaches a NULL character in s 2. 

If s2 is shorter than n characters, strncpy () will append NULL 
characters to si until it has written n characters there. 

The value of si. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


strpbrk 

ANSI 

#include <string.h> 

char *strpbrk(char *sl, char *s2); 

strpbrk () locates the first occurrence of any character from s2 in si. 

A pointer to the first occurrence of any character from s2 in si, if such a 
character is found. 

NULL, if no character from s2 is found in si. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


strrchr 

ANSI 

♦include <string.h> 

char *strrchr(char *s, int c); 

strrchr () locates the last occurrence of c (which it converts to a char) 
in the string that s points to. 

strrchr () considers the terminating NULL character to be part of the 
string s. 

A pointer to c’s last occurrence in the string s, if c is in s. 

NULL, if c is not in s. 
strchr() 
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LIBRARY 


strspn 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


#include <string.h> 

size_t strspn(char *sl, char *s2) 

strspn () computes the length of the maximum initial segment of the 
string that si points to that consists entirely of characters from the string 
that s2 points to. 

The length of the segment (i.e., the position of the first character in si 
that is not in s2). 
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strstr 


LIBRARY 


ANSI 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <string.h 

char *strstr(char *sl, char *s2); 

strstr () looks for string s2 in string si. strstr () does not use the 
NULL terminator in s2, if any, in comparing the two strings. 

A pointer to the found string, if string s2 is in string si. 

NULL, if string s2 is not in string si. 

si, if s2 points to a string with zero length. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


strtod 

ANSI 

#include <stdlib.h> 

double strtod(char *nptr, char **endptr); 

strtod () converts the initial portion of the given string to a double. 

These are the arguments to st rt od (): 

nptr Points to the string that strtod () should convert. 

endptr Pointer to a pointer to any unconverted suffix characters, 

unless endptr is NULL. 

The converted value, if any. 

Infinity matching the sign of the value, if the converted value is outside 
the range of representable values or would cause underflow. It also sets 
errno to ERANGE. 

0 (zero), if it could not perform any conversion. 


142 



ANSI 


3 


LIBRARY 

SYNTAX 
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RETURNS 


strtok 

ANSI 

#include <string.h> 

char *strtok(char *sl, char *s2); 

strtok () breaks a string into tokens. You must call strtok () a sep¬ 
arate time for each token. 

To have strtok () continue to work on the same string, call strtok () 
the first time with the s 1 argument non-NULL. Then call strtok () each 
succeeding time for that string with the si argument set to NULL. (Setting 
the si argument to NULL tells strtok () to continue working on the 
string it was working on at the previous invocation.) 

If strtok () finds the beginning of a token but finds no further delimiter 
characters, the current token extends to the end of the string si, and 
subsequent calls tostrtokO fora token will return a NULL pointer. 

When strtok () finds the end of a token (i.e., it finds a delimiter 
character from s2 at the end of a token in si) it overwrites the found 
delimiter in si with a NULL character, which terminates the current 
token. 

strtok () saves a pointer to the following character, from which 
strtok ()’s next search for a token will start. 

These are the arguments to strtok (): 
s 1 points to the string to be broken up. 

s2 points to a string consisting of valid token delimiters. The 

string that s2 points to may be different from call to call. 
The first character of the token, if it finds a token. 

NULL, if it does not find a token (i.e., if it does not find any characters in 
si that are not in s2, then there are no tokens in string si). 
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LIBRARY 

SYNTAX 

DESCRIPTION 


strtol 

ANSI 

#include <stdlib.h> 

long int strtol(char *nptr, char **endptr, 
int base); 

strtol () converts a string to a long integer. 

These are the arguments to strtol (): 

nptr Pointer to the string that strtol () should convert. 

endptr Pointer to a pointer to any unconverted suffix characters, 

unless endptr is NULL. 

base The base of the number into which strtol () should 

convert the given string. 

If base is between 2 and 36, st rtol () assumes the input is an integer 
in that base. If base is 0 (zero), strtol () assumes the input is an 
integer constant in base 8, 10, or 16. It determines the base of the number 
according to the prefix characters. A leading 0 implies the number is octal 
(base 8); a leading Ox or OX implies the number is hexadecimal (base 16). 

The string should have any number of (or no) white-space characters 
(such as spaces and tabs), followed by the integer, and then any number 
of (or no) unrecognized characters. The integer may be optionally 
preceded by a plus or minus sign. Any integer suffix (such as L or U) is 
ignored. The letters a-z and A-Z are assigned the values 10-35 and can 
be part of the integer if the value of the letter is less than base (e.g. base 
16 integers can include the letters a-f and A-F, which are assigned the 
values 10-15). If base is 16, the integer may be optionally preceded by 
Ox or OX. 

If the input string is empty or consists entirely of white space, or if the first 
non-white-space character is other than a sign or permissible letter or 
digit, strtol () considers the subject sequence to contain no characters, 
and so it performs no conversion. 
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RETURNS 


SEE ALSO 


The converted value as a long integer, if any. 

LONG_MAX, if the converted value is too large for the range of repre¬ 
sentable values. It also sets errno to ERANGE. 

LONG_MIN, if the converted value is too small for the range of repre¬ 
sentable values. It also sets errno to ERANGE. 

0, if it could not convert the string. 

strtoul () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


strtoul 

ANSI 

#include <stdlib.h> 

unsigned long int strtoul(char *nptr, 
char **endptr, int base); 

strtoul () converts a string to an unsigned long integer. 

strtoul () follows essentially the same conversion rules that 
strtol () does. 

These are the arguments to strtoul (): 

nptr Pointer to the string that strtoul () should convert. 

endpt r Pointer to a pointer to any unconverted suffix characters, 

unless endpt r is NULL. 

base Specifies the base of the number into which strtoul () 

should convert the given string. 

The converted value, if any. 

ULONG_MAX, if the converted value is outside the range of representable 
values. It also sets errno to ERANGE. 

0, if it could not convert the string. 

strtol() 
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RETURNS 


strxfrm 

ANSI 

#include <string.h> 

size_t strxfrm(char *sl, char *s2, size_t n); 

strxfrm () is provided for ANSI C compatibility only. According to the 
standard, it transforms the string that s2 points to (preparing the string for 
use with strcmp () ) and places the resulting string in the array that si 
points to. 

In THINK C, strxf rm () simply copies the string to which si points to 
the array to which s2 points, without performing any transformation. 

If n is zero, si can be a NULL pointer. 

The length of the transformed string, not including the terminating NULL. 


147 



Standard Libraries Reference 


LIBRARY 


system 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


#include <stdlib.h> 

int system(char *string); 

system () is provided for ANSI C compatibility only. According to the 
standard, it passes the given string to the host environment for execution 
by a command processor. 

Since the Macintosh has no command processor, THINK C ignores the 
command string and always returns 0 (zero). 

0 (zero) 
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DESCRIPTION 

RETURNS 


tan 

ANSI 

♦include <math.h> 
double tan(double x) ; 

tan () returns the tangent of x, measured in radians. 

The tangent of x, measured in radians. 

Infinity, if x is an odd multiple of ti/ 2. It also sets errno to EDOM. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


taiih 

ANSI 

#include <math.h> 
double tanh(double x); 

tanh () returns the hyperbolic tangent of x. 

The hyperbolic tangent of x. 
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DESCRIPTION 

RETURNS 


time 

ANSI 

#include <time.h> 

time_t time(time_t *timer); 

time () determines the current calendar time. 

If timer is not a NULL pointer, time () assigns the return value to the 
object that timer points to. 

The current calendar time. 

(time_t) -1, if the calendar time is not available. 
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LIBRARY 


tmpfile 

ANSI 


SYNTAX 

DESCRIPTION 


RETURNS 


♦include <stdio.h> 

FILE *tmpfile(void) 

tmpfile () creates a temporary binary file for use by the the program. 

tmpfile () uses write-binary-update mode (wb+, as described in the 
section on f open ()) to open the file for update, tmpfile () will au¬ 
tomatically remove the file when the file is closed (e.g., with f close ()) 
or when the program terminates. 

If the program terminates abnormally, the file is deleted. 

A pointer to the stream of the file created. 

NULL, if it could not create the file. 
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RETURNS 


tmpnam 

ANSI 

♦include <stdio.h> 
char *tmpnam(char *s) ; 

tmpnam () generates a string that is a valid filename and that is not the 
same as the name of an existing file. 

tmpnam () generates a different string each time it is called, up to 
TMP_MAX times. 

If the argument is a NULL pointer, tmpnam () creates a new filename, 
leaves it in an internal static structure, and returns a pointer to that 
structure. 

If the argument is not a NULL pointer, tmpnam () creates a new filename, 
writes the new name into the structure the pointer points to, then returns 
the same pointer. 

A pointer to a structure that contains the new filename. 
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tolower 

LIBRARY ANSI 

SYNTAX #include <ctype.h> 

int tolower(int c); 

DESCRIPTION tolower () converts an uppercase letter to the corresponding lowercase 

letter. 

RETURNS The corresponding lowercase letter. 

c unchanged, if c is not a character for which isupper () is true, or if 
there is no corresponding character for which islower () is true. 
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LIBRARY 


toupper 

ANSI 


SYNTAX 

DESCRIPTION 


#include <ctype.h> 
int toupper(int c); 

toupper () converts a lowercase letter to the corresponding uppercase 
letter. 


RETURNS 


The corresponding uppercase letter. 

c unchanged, if c is not a character for which islower () is true, or if 
there is no corresponding character for which is upper () is true 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


ungetc 

ANSI 

#include <stdio.h> 

int ungetc(int c, FILE *stream); 

ungetc () pushes a single character c back onto the input stream 
stream. 

The next read from that stream will get that character first. On the other 
hand, a successful intervening call to a file-positioning function 
(f seek () , f setpos (), or rewind () ) for the stream stream discards 
any pushed-back characters for that stream. 

ungetc () converts the character to an unsigned char before pushing it 
back onto the input stream. 

If the value of c equals EOF, ungetc () fails and the input stream is 
unchanged. 

c, if successful. 

EOF, if not successful. 
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DESCRIPTION 


va_start 

va_arg 

va_end 

ANSI 

#include <stdarg.h> 
void va_start(va_list ap, parmN) ; 
type va_arg (va_list ap, type); 
void va_end(va_list ap) ; 

These three macros allow a function to step through an argument list 
when the list contains arguments of varying number and type. 

The function declares its variable argument list as follows: 

function (parmN, . . .) 

You must declare at least one named function argument, since 
va_start () uses the last named argument (parmN in the example 
above) to get started. 

You must also declare within the function a variable of type va_list. 
This variable will point to each argument in turn: 

va_list ap; 

First, call va_start (): 

va_start (ap, parmN) ; 

You must call va_start () once before accessing the unnamed ar¬ 
guments. This initializes ap so that it points to the first argument after 
parmN. parmN stands for the last named argument (the one just before 
the “, . . . ”) in the function’s definition. 
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For each unnamed argument, call va_arg (): 
va_arg(ap, type); 

Each call to va_arg () returns one argument and steps ap to the next. 
va_arg () uses the type name type to determine what type of argument 
to return and how big a step down the argument stack to take. 

Lastly, call va_end (): 

va_end(ap); 

va_end () deallocates ap. This allows a normal return from the function. 
You must call va_end () once after processing all its arguments but 
before exiting. 

va_start (), va_arg (), and va_end () are implemented as macros 
rather than actual functions. 

Do not declare parmN as 

• register storage class 

• a function or array type 

• a type that is not compatible with the type that results after application 
of the default argument promotions. 
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DESCRIPTION 


RETURNS 

SEE ALSO 


vfprintf 

ANSI 

#include <stdio.h> 

int vfprintf(FILE *stream, char *format, 
va_list arg); 

vfprintf () performs the same operations as fprintf (), except that 
vfprintf () takes a single argument instead of a variable argument list. 

However, the single argument comes from a variable argument list. The 
calling function must make sure arg is a va_list pointer and has been 
initialized with the va_start () macro (and possibly subsequent 
va_arg() calls). 

vfprintf () does not invoke va_end (). The calling function must 
make sure to do so when appropriate. 

For complete information on format specifiers, read the appendix on 
“printfO / scanfO.” 

The number of characters written, if successful 
A negative value, if failure. 

fprintf (), fscanf() , vprintf(), vsprintf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


vprintf 

ANSI 

#include <stdio> 

int vprintf(char *format, va_list arg); 

vprintf () performs the same operations asfprintfO, except that 
vprintf () takes a single argument instead of a variable argument list. 

However, the single argument comes from a variable argument list. The 
calling function must make sure arg is a va_list pointer and has been 
initialized with the va_start () macro (and possibly subsequent 
va_arg() calls). 

vprintf () does not invoke va_end (), so the calling function must 
make sure to do so when appropriate. 

For complete information on format specifiers, read the appendix on 
“printfO / scanfO.” 

The number of characters written, if successful. 

A negative value, if failure. 


160 



ANSI 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


vsprintf 

ANSI 

#include <stdio.h> 

int vsprintf(char *s, char *format, 
va_list arg); 

vsprintf () performs the same operations as sprintf (), except that 
vsprintf () takes a single argument instead of a variable argument list. 

However, the single argument comes from a variable argument list. The 
calling function must make sure arg is a va_list pointer and has been 
initialized with the va_start () macro (and possibly subsequent 
va_arg{) calls). 

vsprintf () does not invoke va_end (), so the calling function must 
make sure to do so when appropriate. 

For complete information on format specifiers, read the appendix on 
“printfO / scanfO ” 

The number of characters it writes, not counting the terminating NULL 
character, if successful. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


wctomb 

ANSI 

#include <stdlib.h> 

int wctomb(char *s, wchar_t wchar); 

wctomb () is provided for ANSI C compatibility only. THINK C does not 
support multi-byte characters. According to the standard, wctomb () 
converts wchar to a multi-byte character, stores it in the array s points to, 
and returns the length in bytes of the multi-byte character. 

In THINK C, wctomb () sets the first element of s to wchar, if s is not a 
NULL pointer. 

1, if s is not a NULL pointer. 

0, if s is a NULL pointer, 
mblen(), mbtowc() 
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LIBRARY 

SYNTAX 


DESCRIPTION 


RETURNS 
SEE ALSO 


wcstombs 

ANSI 

#include <stdlib.h> 

size_t wcstombs(wchar_t *pwcs, char *s, 
size_t n); 

wcstombs () is provided for ANSI C compatibility only. THINK C does 
not support multi-byte characters. According to the standard, 
wcstombs () converts a sequence of codes to a multi-byte character 
string, stores it in the array s points to, and returns the number of array 
elements changed. 

In THINK C, wcstombs () simply copies the elements of pwcs to s, 
stopping after it copies n elements or a NULL character. 

The number of characters copied. 

mblen(),mbstowcs() 
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Introduction 

This chapter describes THINK C’s console library and includes a complete listing of all the 
functions it contains. 

Topics covered in this chapter: 

• What is the console library? 

• What is a console? 

• Environments 

• Options 

• A catalogue of functions 

What Is the Console Library? 

The console library makes available to programs a group of routines that perform certain 
console operations, such as creating and moving in console windows. 

To perform I/O involving one of the ANSI standard streams (stdin, stout, stderr), 
simply add the ANSI library to your project, described in Chapter 3, “ANSI.” The console 
package automatically creates a console window and associates these streams to that win¬ 
dow by default. You need to add the console library to your project only if you explicitly 
call one of the console functions described in the following catalogue. 

Using the console library 

To use the console functions, simply add the console library to your project and ^include 
the console . h file in any file that uses console functions. 


What Is a Console? 

A console is a Macintosh window that behaves like a glass tty or a dumb terminal, (“tty” is an 
abbreviation for “teletypewriter.”) A program can create additional consoles. 

How does a program use console functions? 

Your program doesn’t need to call the console library routines directly. The ANSI library calls 
the console library automatically in order to perform console-related I/O operations. 
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If you do want your THINK C program to use the console library routines directly, make sure 
the program’s file includes console . h and make sure the ANSI library is added to your 
THINK C project. 

You can then make calls to the console library routines, and I/O will proceed according to 
the environment in which the program is running. Environments are explained in the next 
section. 

A generally useful console function is ccommand (), which allows you to enter command¬ 
line arguments, including directions to redirect stdin, stdout, and stderr to files. 

Console routines are not completely portable 

Keep in mind that once you explicitly incorporate THINK C console library routines into 
your programs (as opposed to having ANSI library routines call them automatically), your 
programs no longer will be portable out of the Macintosh environment. 

Environments 

You can use the console package in two environments: the generic console environment 
and the Macintosh environment. 

The console package automatically selects between the two environments, partly on the ba¬ 
sis of initialization calls that appear in regular Macintosh programs. 

Generic Console Environment 

In this environment, the console package supplies a default menu bar, and its windows are 
the only windows. 

Programs must be written in plain C (or ported from a Unix or MS-DOS environment). That 
is, you can not use the Macintosh Toolbox or other Macintosh facilities. 

In this environment, consoles can be used for both input and output, as they are in C. 

Macintosh Environment 

In the Macintosh environment, your program is a Macintosh-style program, as opposed to a 
plain C program. It has its own event loop, menus, and windows. By using the console 
package, the program has the additional ability to output to a console window. 

The window has whatever menu bar the program gives it. The program can create as many 
windows as it wishes, and the windows can coexist with other windows from other 
programs. 

In the Macintosh environment, consoles can be used for output only. 
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Options 

To set options for a console, the program sets elements in a global structure called 
console_options. This structure resides in console, h and looks like this: 

struct { 


short 

top; 

short 

left; 

char 

*title; 

short 

procID; 

short 

txFont; 

short 

txSize; 

short 

txFace; 

short 

nrows; 

short 

ncols; 

short 

pause_atexit; 


}; 


When the program changes the contents of console_options, the changes affect the 
characteristics of the next console to be created. 

Remember, once a console is created, its characteristics cannot be changed. 

The functions that use the settings in console_options are fopenc () and freopenc (). 

Input Modes 

Console input can proceed in one of four modes, as follows: 

C_ECHO line-buffered, echo, full editing 

C_NOECHO line-buffered, no echo, partial editing 

C_CBREAK unbuffered, echo, no editing 

C_RAW unbuffered, no echo, no editing 

In the line-buffered modes (C_ECHO and C_NOECHO): 

• The console package does not make input available to the program until the program’s 
user types a newline (RETURN or ENTER). (For example, a readline () call won’t re¬ 
turn until the user has entered the whole line.) 

• The user may edit the line as they type it using backspace (DELETE) or line-erase 
(control-U, ESC, CLEAR). 

• Control-D signifies keyboard end-of-file. (Useful for emulating a true EOF.) 
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In the unbuffered modes, the console package makes input available to the program as soon 
as each character is typed: 

• In C_RAW mode, the console package does not perform any special interpretation of 
characters at all. Input requests do not block, that is, if the program calls get char () and 
the user has not typed any characters, get char () returns EOF immediately. 

• In C_BREAK mode, the console package makes input available to the program after a 
single character is typed. In effect, this is as if C_RAW mode were echoing. 

Video Modes 

There are two video modes: normal and inverse. 

When your program enables inverse video, the console package cannot use the characters in 
the upper half of the character set. This is because the console package uses the high bit of 
each displayed character to denote whether the character should be displayed in normal or 
inverse video. This also means that the program must make sure that control characters that 
it wishes to output, such as '\n 1 , do not have their high bits set. 

Remember, cinverse () does not turn inverse on or off. It only enables inverse video to be 
turned on or off. Other software must flip the bits in the characters that are to be displayed in 
order for for them to appear in inverse video. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


ccleol 

console 

#include <console.h> 
void ccleol(FILE *fp); 

Clear to end of line. 

ccleol () erases characters that follow the cursor and are on the same 
line that it is on, in the console that fp refers to. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


ccleos 

console 

#include <console.h> 
void ccleos(FILE *fp); 

Clear to end of screen. 

ccleos () erases the line containing the cursor and all lines that follow it 
to the end of the screen, in the console that f p refers to. ccleos () 
leaves the cursor at the start of the first erased line. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


ccommand 

console 

#include <console.h> 
int ccommand(char ***p); 

Get command line. 

ccommand () provides Unix-style I/O redirection and command-line 
processing. 

Call ccommand () from main () as follows: 

main (int argc, char **argv) 

{ 

argc = ccommand(&argv); 

} 

ccommand () displays a dialog that lets you enter command-line ar¬ 
guments and redirect stdin and stdout. 

The number of command-line arguments, argc. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


cecho2file 

console 

#include <console.h> 

void cecho2file(char *file, int append, FILE *fp); 
Echo output to file. 

cecho2file () echoes to a file named file complete lines that any 
program subsequently writes to the console that fp refers to. 

If the file exists and append is non-zero, cecho2f ile () writes the 
echoed lines to the end of the file. If the file doesn’t exist, 
cecho2f ile () creates it now and writes the echoed lines to the file. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


cgetxy 

console 

#include <console.h> 

void cgetxy(int *x, int *y, FILE *fp) ; 

Report cursor position. 

cgetxy () stores the current position of the cursor into *x and *y, 
where x is for the column and y is for the row, and the upper left corner 
is at 1, 1. fp refers to the console that the cursor belongs to. 
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LIBRARY 


cgotoxy 

console 


SYNTAX 

DESCRIPTION 


#include <console.h> 

void cgotoxy(int x, int y, FILE *fp) 

Set cursor position. 

cgotoxy () positions the cursor to x and y , where x is the column and 
y is the row. The upper left corner is 1, 1. fp refers to the console that the 
cursor belongs to. 

Note: cgotoxy () does not check its arguments. Be careful not 
to put the cursor off-screen. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


chide 

console 

#include <console.h> 
void chide(FILE *fp) ; 

Hide console. 

chide () makes invisible the console that fp refers to. 
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cinverse 


LIBRARY 


console 


SYNTAX 

DESCRIPTION 


#include <console.h> 

void cinverse(int x, FILE *fp); 


Enable or disable inverse video mode in the console that fp refers to. 


cinverse() 
Zero 

Non-zero 


sets the inverse video mode according to the value of x: 
disables inverse video mode, 
enables inverse video mode. 


cinverse () erases the entire window and moves the cursor to the start 
of its line. 


When a console is created, inverse video is disabled. 

For more information, read the section “Video Modes” above. 

Remember, cinverse () does not turn inverse on or off. It only enables 
inverse video to be turned on or off. Other software must flip the bits in 
the characters that are to be displayed in order for for them to appear in 
inverse video. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


csetmode 

console 

#include <console.h> 

void csetmode(int mode, FILE *fp); 

Set input mode. 

csetmode () sets the input mode of the console. This resetting affects 
subsequent input, but it does not affect characters that are already 
buffered. 


These are the arguments to csetmode (): 


mode 


fp 


Specifies the mode in which the console will operate, 
mode can have one of four values: 

C_ECHO line-buffered, echo, full editing 
C_NOECHO line-buffered, no echo, partial editing 
C_CBREAK unbuffered, echo, no editing 
C_RAW unbuffered, no echo, no editing 
Pointer to the console. 


When a console is created, the input mode is initially C_ECHO. 

For more information on these modes, read the section “Input Modes” 
above. 


177 


Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 


csettabs 

console 

#include <console.h> 

void csettabs(int n, FILE *fp); 

Set tab stops. 

csettabs () sets tab stops every n spaces in the console that fp refers 
to. 

This resetting of the tab stops affects subsequent output, but it does not 
change output that is already displayed. 

When a console is created, tabs stops are initially set every 8 spaces. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


cshow 

console 

#include <console.h> 
void cshow(FILE *fp); 

Show and select console. 

cshow () makes visible the console window that fp refers to and brings 
it to the front of the Macintosh screen. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


fopenc 

console 

#include <console.h> 

FILE *fopenc(void); 

Open a file. 

fopenc () creates a new console and opens a new stream on that 
console. 

To set options for the console, set the elements in the global structure, 
console_options. (This structure resides in console . h and is de¬ 
scribed in detail in the section “Options”.) 

When the program changes the contents of console_options, the 
changes affect the characteristics of the next console to be created. And 
remember, once a console is created, its characteristics cannot be 
changed. 

A pointer to a console. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


freopenc 

console 

♦include <console.h> 

FILE *freopenc(FILE *fpl, FILE *fp2); 

Open a console on a specific stream. 

First, freopenc () closes the stream that fp2 refers to, if necessary. It 
then reopens it as a console as follows: 

• If f pi is NULL, fp2 is a pointer to a newly-created console. 

• If f pi is not NULL and refers to a console, f p2 will refer to that 
console, too. 

A pointer to a console. 
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This chapter describes THINK C’s unix library and includes a complete catalogue of the 
functions it contains. 

Topics covered In this chapter: 

• What is the Unix library? 

• A catalogue of functions 

What Is the Unix Library? 

The unix library implements a few functions common to many Unix implementations of C 
that were not included in the ANSI standard library. It includes functions to handle files, sig¬ 
nals, and other Unix-specific features. 

Using the Unix library 

To use the unix library, add it to your project and #include the unix. h file in any file that 
uses its functions. 

Do not use the unix library in any newly-created programs. Instead, use it to make porting 
software from Unix systems easier. Its functions have equivalents in the ANSI standard li¬ 
brary and the Macintosh system software. 

Files 

The file-handling functions in the unix library are similar to the ones in the ANSI library. 
The most significant difference between the two sets of functions is how the libraries refer to 
files. While the ANSI library uses stream pointers , the unix library uses small non-negative 
integers. These numbers are not all related to Macintosh refnums. For compatibility with 
Unix and MS-DOS, the numbers 0, 1, and 2 refer to stdin, stdout, and sterr, 
respectively. 
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These Unix and ANSI file-handling functions are roughly equivalent: 


Unix library: 

open() 
close () 
read() 
write () 
fdopen () 
creat () 
lseek () 
tell() 


ANSI library: 

fopen() 
fclose () 
freadO 
fwrite() 
freopen() 
fopen() 
fseek() 
ftell() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


close 

Unix 

#include <unix.h> 
int close(int fn) ; 

close () closes the file whose file descriptor number is f n. 

fn is the number returned by the latest creat () or open () call that 
opened the file. 

0, if successful 

-1, if failure. 

open(),creat(), read(), write(). 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


creat 

Unix 

♦include <unix.h> 

int creat(char *filename, int mode); 

creat () creates and opens a new file. If the file already exists, 
creat () will truncate its size to zero. 

mode specifies the mode in which creat () will open the file. For more 
information on this argument, see open () in this chapter, creat () is, 
in effect, a special case of the open () function. 

The file descriptor number of the newly created and opened file, if 
successful 

EOF, if failure. 

open(), close(), read(), write() 
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exec 

execl 

execle 

execlp 

execlpe 

execv 

execve 

execvp 

execvpe 


LIBRARY 


Unix 


SYNTAX 


DESCRIPTION 


RETURNS 


♦include <unix.h> 

int exec(char *path, . . . ) ; 

int execl(char *path); 

int execle(char *path); 

int execv(char *path, char argv[]); 

int execve(char *path, char *argv[], char *envp[]); 
int execvp(char *path, ...); 
int execvpe(char *path, ...); 

These functions launch the file named in path. 

These functions ignore all arguments except the path argument (first 
argument). 

Nothing. (A successful exec () call never returns.) 
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LIBRARY 


fdopen 

Unix 


SYNTAX 

DESCRIPTION 

RETURNS 


#include <unix.h> 

FILE *fdopen(int fn, char mode); 

fdopen () returns a pointer to the stream that the file descriptor fn refers 
to. mode is ignored. 

A pointer to the stream associated with the given file descriptor. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


Unix 

♦include <unix.h> 

int fileno(FILE *stream); 

f ileno () returns the file descriptor number of stream, where 
stream is a pointer to a file descriptor. 

The file number of stream, if successful. 

EOF, if failure 

FILE, open (), close (), fopen (), f close () 
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LIBRARY 


getegid 

geteuid 

getgid 

getpgrp 

getpid 

getppid 

getuid 

Unix 


SYNTAX 


DESCRIPTION 


♦include <unix.h> 
int getegid(void) ; 
int geteuid(void) ; 
int getgid(void) ; 
int getpgrp(void) ; 
int getpid(void) ; 
int getppid(void) ; 
int getuid(void) ; 


Thes functions are provided for Unix compatibility only. In THINK C, 
they return numbers that are intended to mimic their respective entities 
but have no real meaning in the Macintosh environment. 


Function: 

getegid() 
geteuid() 
getgid () 
getpgrp() 
getpid() 
getppid () 
getuid() 


Returned value: 

Group ID. 

User ID. 

Process’s group ID. 

Process group ID of the calling process. 
Program’s process ID number. 

Calling process’s parent's process ID. 
Program’s user ID number. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


getlogin 

Unix 

♦include <unix.h> 
char *getlogin(void) ; 

getlogin () returns the user name set in the Chooser desk accessory. 
(In the Unix environment, getlogin () returns the username under 
which the program was started.) 

The user name set in the Chooser desk accessory. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


getw 

Unix 

♦include <unix.h> 

int getw(FILE *stream); 

getw () returns the next two bytes of stream as an integer. 

getw () assumes the bytes are in memory order (that is, according to the 
MC68000 convention, with the MSB in the first byte). 

An integer representing the next two bytes of stream, if successful 

EOF, if failure. 

putw() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


is a tty 

Unix 

#include <unix.h> 
int isatty(int fn) ; 

isatty () tests whether or not a stream is associated with a console. 

This is useful for verifying that a user will see messages that are printed to 
the stream, and if, on EOF, it makes sense to ask for more input from the 
stream. 

Use isatty () this way: 
isatty(fileno(fn)); 
where f n is a pointer to a stream. 

Non-zero, if the given stream pointer refers to a console. 

Zero, if the given stream pointer refers to anything else. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


kill 


Unix 

#include <unix.h> 

int kill(int pid, int sig) ; 

In Unix, kill () sends the signal sig to the process specified by pid. 
However, the Macintosh does not support interprocess communication. 
So, kill () can send the signal to its own application only. 

In THINK C, kill () raises the signal sig if sig is not zero and if pid is 
one of the following: 0,-1, the value returned by get pid (), or the 
negative of the value returned by getpgrp (). If pid is not one of those 
values, kill () returns -1 and sets errno to ESRCH. 

0, if successful. 

-1, if failure. It also sets errno to ESRCH. 

signal () (in the ANSI library), raise () (in the ANSI library) 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 

SEE ALSO 


unix 5 


lseek 

Unix 

♦include <unix.h> 

long lseek(int fn, long offset, int whence); 

lseek () sets the file position indicator for the given file. (The file 
position indicator measures the position in characters from the beginning 
of the file.) It is much like f seek (), except that lseek () takes a file 
descriptor number instead of a pointer to a file. For more information, see 
the section f seek () in the ANSI chapter. 

These are the arguments to f seek (): 
f n The file descriptor number for the file, 

offset The amount of space in the file through which to seek, 

whence The position from which to start seeking. 

These macros are useful values for whence: 

SEEK_SET The beginning of the file. 

SEEK_CUR The current value of the file position indicator. 

SEEK_END The end of the file. 

The value of the file position indicator, if successful 

EOF, if unsucessful. 

fseek() (in the ANSI library). 
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open 

LIBRARY Unix 

SYNTAX #include <unix.h> 

int open(char *filename, int mode); 

DESCRIPTION open () opens a filename for reading or writing, according to mode. 

open () returns the file descriptor number of the open file. 

mode is a flag word that you set by OR-ing together various flags. These 
flags determine how open () will open the file. The flags are defined in 
f cntl. h. 

Opening Flags: mode must have exactly one flag from this group: 
0_RD0NLY Open this file for reading only. 

0_WR0NLY Open this file for writing only. 

0_RDWR Open this file for reading and writing. 

mode may have any number of flags from this group: 

Set the file position indicator to the end of the file prior 
to each write. 

Create the file if it doesn’t already exist. 

If the file exists, reset its length to 0 (zero). Leave the 
mode and owner unchanged. 

If the file exists, don’t create it again, but do set the file 
position indicator to the beginning of the existing file. 

File-Type Flags: mode may have at most one flag from this group: 
0_TEXT Text file. 

O_BINARY Binary file. 

If neither file-type flag is set, open () uses the global variable _fmode, 
declared in f cntl. h. The initial value of _fmode is 0_BINARY. The 
user may change this value by assigning it at runtime. The value of 
_fmode does not affect the mode of files opened with f open (). 

SEE ALSO close(), creat(), read(), write() 


Creation Flags: 
0_APPEND 

0_CREAT 
O_TRUNC 

O EXCL 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


putw 

Unix 

#include <unix.h> 

int putw(int word, FILE *stream); 

putw () writes word as two bytes — the high byte and then the low byte 
— to the given output stream. 

putw () assumes the bytes are in memory order (that is, according to the 
MC68000 convention, with the MSB in the first byte). 

word, if successful. 

EOF, if failure. 

getw() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


read 

Unix 

♦include Cunix.h> 

int read(int fn, char *buffer, unsigned int count) 
read () tries to read a number of bytes from a file into an array. 

These are the arguments to read (): 

f n File descriptor number of the File from which to read. 

buffer Buffer to read into. 

count The number of bytes to read. 

The number of bytes read, if successful 

The number of bytes read before end-of-file, if the end of the File is 
reached. (Unix systems return 0.) 

EOF, if failure. 

write (),open(), close() 
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SYNTAX 

DESCRIPTION 


sleep 

Unix 

#include <unix.h> 
void sleep(int secs); 

sleep () waits secs seconds and then continues. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 

SEE ALSO 


tell 

Unix 

#include <unix.h> 
long tell(int fn) ; 

tell () returns the current value of the file position indicator for the file 
descriptor number fn. 

The current value of the file position indicator for the given stream f n, if 
successful. 

EOF, if failure. 

f tell () (in the ANSI library), fseek (), seek () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURNS 


unlink 

Unix 

#include <unix.h> 

int unlink(char *filename); 

unlink () deletes the file filename. 

If the file is open, unlink () will return an error and leave the file 
unchanged. 

0, if successful. 

-1, if failure. 


201 



Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURNS 


SEE ALSO 


write 

Unix 

#include <unix.h> 

int write(int fn, char *buffer, unsigned nbytes) 
write () copies bytes from a buffer to a file. 

These are the arguments to write (): 

f n File descriptor number of the file to write to. 

buffer BufTerf rom which to copy bytes, 

nbytes Number of bytes to copy. 

The number of bytes it copied, if successful. 

-1, if failure. 

read(), open(), close() 
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This appendix describes the format arguments used with the following functions: 

fprintfO fscanf () 

printf() scanf() 

sprintfO sscanf () 

vfprintf() 
vprint() 
vsprintf() 

Topics covered In this chapter: 

• Structure of format arguments 

• Format arguments for printf (). 

• Format arguments for scanf (). 

• Common errors. 

Structure of Format Arguments 

Each format argument can have a variable number of format specifiers. Each format speci¬ 
fier, in turn, is composed of a variable number of directives, most of which are single 
characters. 

In general, a format specifier must begin with a percent sign (%) and end with a conversion 
character. Between the % and the conversion character, there may be the following direc¬ 
tives, in order: 

• Zero or more flags, in any order, that modify the meaning of the rest of the format 
element. 

• A number that specifies the minimum field width into which or out to which the 
function will put the data. 

• A period, which separates the field width from the precision. 

• A number, the precision, that specifies the number of characters or digits to print. 

• An h,l Getter ell), or L that specifies the size of the argument. 

To summarize, the format specifiers for printf () -related functions have this form (where 
brackets indicate a choice of optional values): 

% [flags] [ field-size ] [. precision ] [ arg-size] conversion 
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And the format specifiers for scanf () -related functions have the form (where brackets 
indicate a choice of optional values): 

% [flags] [field-size] [arg-size] conversion 

The following sections describe the format arguments for print f () -related functions and 
scanf () -related functions. Generally, the format arguments behave the same in both scan 
and print functions. Where differences occur, the text notes them in detail. 

Format Arguments for printf() 

This section describes the format specifiers you can use to construct format arguments for 
the printf () -related functions: fprintf (), printf (), sprintf (), vfprintf (), 
vprintf (), and vsprintf (). 

The format arguments for these functions have the following syntax: 

flags field size precision arg size conversion 

% [-+<space># 0] [*<integer>] [. * <integer>] [hlL] cdeEfgGinopsuxX% 

The following sections describe each of the format directives in this diagram in detail. 


Flag character 

A flag character modifies the specification in some way. Any number of flags are allowed in 
a specification. These are the flags: 


Directive 

Meaning 

(hyphen) 

Left-justifies what’s printed within the field. 

+ 

(plus sign) 

Prints a positive number with a plus sign. (Otherwise, a sign character is 
printed only when a number is negative.) 

i i 

(space) 

Prefixes a number with a space, if one of these is true: 

• The first character of a signed numeric conversion is not a sign. 

• A signed numeric conversion has no characters. 

If both the space and + flags appear, the space flag is ignored. 
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Directive 

Meaning 

# 

(pound) 

Converts what’s to be printed to an alternate form: 

• For o conversion, increases the precision to force the first digit of the 
result to be zero. 

• For x (or X) conversion, prefixes Ox (or OX) to a nonzero result 

• For e, E, f, g, and G conversion, always includes a decimal point in 
the result, even if no digits follow the decimal point. 

• For g and G conversions, does not remove trailing zeros from the 
result. 

• For s conversions, accepts a Pascal-style string (an object of type 

Str2 55). This is a THINK C extension. 

0 

(zero) 

Pads the field with leading zeros (inserting them after any indication of 
sign or base) for d, i, o, u, x, X, E, f, g, and G conversions. For d, i, o, u, 
x, and X conversions, if there's precision specification, the 0 flag is ig¬ 
nored. If both the 0 and - flags appear, the 0 flag is ignored. 


Field size 

The field size directive specifies the width of the field into which the function will print the 
converted data argument. The field size directive can be one of these: 


Directive 

Function 

★ 

(asterisk) 

Uses the next directive in the format specifier, which must be an integer, 
as the size for the field size into which it will print the data. 

an integer 

Uses this integer as the size for the field into which it will print the data. 


If the data the function prints has fewer characters than the field size, the function will pad 
the output with spaces on the left or right, depending on what flags are present. 
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Precision directive 

The precision directive specifies one of these, depending on the argument that follows: 


Arg. 

The precision directive specifies... 

string 

The maximum number of characters to print from the string. 

floating¬ 

point 

number 

The number of digits after the decimal point of the floating-point value to 
print. 

integer 

The minimum number of digits to print. 


The precision directive is a period (.) followed optionally by one of the following: 


Directive 

Meaning 

a decimal 
integer 

Use this integer as the precision. 

★ 

(asterisk) 

Use the next argument as the precision specifier. That argument must be 
an integer. 


If neither an integer nor an asterisk appear, the function assumes a precision of 0. 

Note: When an asterisk appears in the field size and precision directives of 
a format specifier, make sure the arguments to which they refer appear im¬ 
mediately after the format argument in this order: field size, precision, and 
the argument to print. 


Argument size 

The argument size specifies the size of the argument. It can be one of the following: 


Directive 

Meaning 

h 

This d, i, o, u, x, or X conversion specifier applies to an argument of type 
short int or unsigned short int. Converts the argument before 
printing, if necessary. 

1 

Getter ell) 

This d, i, o, u, x, or X conversion specifier applies to an argument of 
type long int or an unsigned long int. Converts the argument be¬ 
fore printing, if necessary. 

L 

This e, E, f, g, or G conversion specifier applies to an argument of type 
long double. Converts the argument before printing if necessary. 


h, 1, and L are not valid with any other conversion specifiers. 
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Conversion characters 

The conversion character specifies how the argument should be printed. These are the con¬ 
version characters: 


Character Argument Type 

Output 

c int 

A single character 

d int 

A signed decimal integer. 

[-] dddd 

e, E double 

A signed decimal floating point number. 

[ - ] m.ddde±xx (for e) 

[ - ] m.dddEztxx (for E) 

• Prints one digit before the decimal point. 

• Prints the number of digits after the decimal 
point specified by the precision directive. The 
default is 6. 

• If the precision directive is 0 and there is no # 
flag in this format specifier, this does not print a 
decimal point. 

• Rounds the value to the appropriate number of 
digits. 

f double 

A signed decimal fixed-point number. 

[-] mmm. ddd 

• Prints the number of digits after the decimal 
point specified by the precision directive. The 
default is 6. 

• If the precision directive is 0 and there is no # 
flag in this format specifier, this does not print a 
decimal point. 

• If this prints a decimal point, it prints at least 
one digit before the decimal point. 

• Rounds the value to the appropriate number of 
digits. 

g double 

Uses the f or e format, whichever is smaller 

G double 

Uses the f or E format, whichever is smaller. 
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Character Argument Type 

Output 

i int 

A signed decimal integer. 

[-] dddd 

• Pads the result with leading zeros if there are 
fewer digits than the precision directive allows. 

• The default precision is 1. 

• If the value is zero and the precision is zero, 
this prints nothing. 

n int * 

Nothing printed. 

This puts into an integer the number of characters 
the function has printed so far during this call. 

0 unsigned int 

An unsigned octal integer. 

dddd 

• Pads the result with leading zeros if there are 
fewer digits than the precision directive allows. 

• The default precision is 1. 

• I f the value is zero and the precision is zero, 
this prints nothing. 

p void * 

An eight-digit hexadecimal value. 

s char * 

Str255 

A string. 

Without the # flag, this specifier prints a C-style 
string (an object of type char *). It prints the 
string until one of the following happens: 

• It encounters a NULL character, which it will 
not print. 

• It prints the maximum number of characters 
allowed by the precision directive. 

With the # flag, this specifier prints a Pascal-style 
string (an object of type Str255). 

u unsigned int 

An unsigned decimal integer. 

• Pads the result with leading zeros if there are 
fewer digits than the precision directive allows. 
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Character 

Argument Type 

Output 

x, X 

unsigned int 

An unsigned hexadecimal integer. 

• If the directive is x, this uses a, b, c, d, e, and f 
as the extra digits. 

• If the directive is X, this uses A, B, C, D, E, and F 
as the extra digits. 

• Pads the result with leading zeros if there are 
fewer digits than the precision directive allows. 

% 

No argument used 

A percent sign (%) 


Format Arguments for scanf() 

This section describes the format specifiers you can use to construct format arguments for 
the scanf () -related functions: f scanf (), scanf (), and sscanf (). 

The format arguments for these functions have this syntax: 

flag field size arg size conversion 

% [*] [<inleger>] [hlL] cdefginopsux% [...] 

The following sections describe each of the format specifiers in this diagram in detail. 

Flag character 

The flag character controls whether the input field that matches the specifier is ignored. 


Directive 

Meaning 

★ 

(asterisk) 

Suppresses the assignment of the input field that matches this specifier. 


Field size 

The field size directive specifies the width of the input field. 


Directive 

Meaning 

a decimal 
integer 

Specifies the width of the field from which this conversion specifier will 
read the converted data argument(s). 
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Argument size 

The argument size directive specifies the size of the argument. These are the argument size 
directives: 


Directive 

Meaning 

h 

Specifies that this conversion specifier applies to an argument of the fol¬ 
lowing type: 

• For d, i, or n specifiers, short int *. 

• For o, u, or x specifiers, unsigned short int *. 

1 

Getter ell) 

Specifies that this conversion specifier applies to an argument of the fol¬ 
lowing type: 

• For d, i, or n specifiers, long int *. 

• For o, u, or x specifiers, unsigned long int *. 

• For e, f, or g specifiers, double *. 

This can also specify than the n conversion specifier applies to an object 
of type long int *. 

L 

Specifies the e, f, or g conversion specifier applies to an argument that is 
pointer to a long double. 


h, 1, and L are not valid with any other conversion specifiers. 

Conversion characters 

The conversion character specifies how to interpret the input field. These are the conversion 
characters: 


Character 

Argument Type 

Input 

c 

char * 

A single character 

• Accepts all kinds of characters: white space, 
control characters, etc. 

• The pointer must point to an object large 
enough to hold all the characters specified. 

• Does not add a terminating NULL. 

d 

int * 

A decimal integer 

e, f, g 

float * 

A floating-point number with optional sign, deci¬ 
mal point, and exponent integer. 
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Character 

Argument Type 

Input 

i 

int * 

An integer 

Figures the base of the number according to its 
appearance: 

• Leading 0 means it’s octal (base 8). 

• Leading Ox or OX means it’s hexadecimal (base 
16). 

• Otherwise, it’s decimal (base 10). 

n 

int * 

No argument read. 

Puts into its argument the number of characters the 
function has read so far during this call. 

o 

unsigned int * 

An octal integer. 

P 

void * 

A hexadecimal number. 

s 

char * 

A character string. 

• Reads only non-white-space characters. 

• The pointer must point to a memory area that is 
large enough to hold all the characters. 

• Adds a terminating NULL. 

u 

unsigned int * 

A decimal integer. 

X 

unsigned int * 

A hexadecimal integer. 

% 

No argument filled 

A percent sign (%). 

[...] 

char * 

Read section “Scan sets” below. 


Scan sets 

Scan sets allow you to determine exactly which characters are read into a string argument. In 
a scan set of the form % [...] you can list just the characters you want to read. In a set of the 
form % [X-X] you can give a range of characters you want to read. The range is determined 
using the ASCII ordering sequence. And in a set of the form % [ *...] you can specify the 
characters you do not want to read. 
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Here are several example scan sets: 


Scan set 

Read the longest string of characters in which... 

%[xyz] 

all are x, y, or z. 

%[ A xyz] 

none are x, y, or z. 

%[]xy z] 

all are x, y, z, or the right bracket. 

M A ]xyz] 

none are x, y, z, or the right bracket. 

%[a-z] 

all are lowercase alphabetic characters (from a to z). 

% ["a-z] 

none are lowercase alphabetic characters (from a to z). 

%[-xyz] 

all are x, y, z, or the hyphen. 

%[xyz-] 

all are x, y, z, or the hyphen. 

%["-xyz] 

none are x, y, z, or the hyphen. 


Common Errors 

• Make sure there is one variable argument of the correct size for each format specifier in 
format. 

• Make sure all arguments are of the right type. 

• A common misconception about print f () is that print f () “knows” about its argu¬ 
ments. If you pass a long expression to print f (), you must specify in the format string 
that you want a long expression to be printed. Example: 

int anlnt; 
long aLong; 

printf("long is %ld, int is %d\n", aLong, anlnt); 

In scant, the same goes for floats and doubles: 

float aFloat; 
double aDouble; 

printf("Input a double and a float:"); 
scant ("%lf %f", SaDouble, SaFloat); 
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Entries in bold face refer to menu commands. Entries in typewriter face refer to 
functions, methods, variables, keywords, or files. 
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free 68 
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0_RDWR 196 
0_TEXT 196 
0_TRUNC 196 
0_WR0NLY 196 
offsetof 15 
open 196 
perror 101 
pow 102 
printf 103 
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putc 104 
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puts 106 
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qsort 107 
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rand 109 
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srand 122 
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stderr 17 

stdin 17 

stdio.h 16 

stdlib.h 19 

stdout 17 
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License Agreement 

This manual and the software described in it were developed and are copyrighted by 
Symantec Corp. (Symantec) and are licensed to you on a non-exclusive, non-transferable 
basis. Neither the manual nor the software may be copied in whole or in part except as 
follows: 

1) You may make backup copies of the software for your use provided that they bear 
Symantec’s copyright notice. 

2) You have the right to include object code derived from the libraries in programs that you 
develop using the software and you also have the right to use, distribute and license 
such programs to third parties without payment of any further license fees, so long as a 
copyright notice sufficient to protect your copyright in the software in the United States 
or any other country is included in the graphic display of your software and on the la¬ 
bels affixed to the media on which you software is distributed. 

You may not in any event distribute any of the source files provided or licensed as part of 
the software. You may use the software at any number of locations so long as there is no 
possibility of it being used at more than one location at a time. 

Symantec’s Plain Language License Statement 

Symantec is concerned with how you copyright your software only in the case where you 
use object code of libraries which Symantec provides in source form (MacTraps does not fall 
into this category). These libraries may be included in your program so long as a copyright 
notice that will protect your copyright in the software is in the “About box” of your software 
and on the disk labels, as specified in the license agreement. You are not required to include 
a specific Symantec copyright notice except if your copyright does not satisfy the above re¬ 
quirement. This is only an explanation of the License Agreement. All terms and conditions 
of the License Agreement apply. 

Limited Warranty on Media and Manuals 

If you discover physical defects in the media on which this software is distributed or in the 
manuals distributed with the software, Symantec will replace the media or manuals at no 
cost to you provided that you return the defective materials along with a copy of your receipt 
to Symantec or to an authorized Symantec dealer during the 60-day period following your re¬ 
ceipt of the software. 

Limited Warranty on the Product 

Symantec warrants that the software will perform substantially as described in the User’s 
Manual. If within 60 days of receiving the software, you give written notification to Symantec 
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of a significant, reproducible error in the software which prevents operation, and provide a 
written description of the possible problem along with a machine readable example, if ap¬ 
propriate, Symantec will either provide you with corrective or workaround instructions, a 
corrected copy of the software, a correction to the User’s Guide and Reference Manual, or 
Symantec will refund your purchase price upon return of all copies of the software and doc¬ 
umentation together will a copy of your receipt. This warranty extends only to you and shall 
be void if the software has been tampered with, modified, or improperly used, or if the soft¬ 
ware is used on hardware other than the Apple Macintosh™ Computer. 

EXCEPT FOR THE LIMITED WARRANTY DESCRIBED ABOVE, THERE ARE NO WAR¬ 
RANTIES TO YOU OR ANY OTHER PERSON OR ENTITY FOR THE PRODUCT EXPRESSED 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OR MER- 
CHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. ALL SUCH WARRANTIES ARE 
EXPRESSLY AND SPECIFICALLY DISCLAIMED. Some states do not allow the exclusion of 
implied warranties or limitations on how long they last, and you also may have other rights 
that vary from state to state. IN NO EVENT SHALL SYMANTEC BE RESPONSIBLE FOR ANY 
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR SIMILAR DAMAGES OR LOST 
DATA OR PROFITS TO YOU OR ANY OTHER PERSON OR ENTITY REGARDLESS OF THE 
LEGAL THEORY, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGE. Some states do not allow the exclusion or limitation of incidental or consequential 
damages, so the above limitation or exclusion may not apply to you. The warranty and 
remedies set forth are exclusive and in lieu of all others, oral or written, express or implied. 

SYMANTEC MAKES NO WARRANTY OF THE PERFORMANCE OF THE LIBRARIES WHEN 
USED IN YOUR SOFTWARE. YOU AGREE TO INDEMNIFY SYMANTEC FROM ALL CLAIMS 
BY THIRD PARTIES ARISING IN CONNECTION WITH THE USE OF YOUR SOFTWARE. 

General Terms This license states the entire agreement between the parties and supersedes 
all other communications between the parties relating to this License, which shall be gov¬ 
erned and construed in accordance with the laws of the State of California. You agree to 
bring any proceeding to enforce or construe this License or involving the performance of the 
software only in a federal or state court residing in the State of California. The prevailing 
party in any such proceedings shall be entitled to recover its attorneys’ fee and litigation ex¬ 
penses in addition to other appropriate relief. If any provision of this License by Symantec 
shall be held to be unenforceable such holding shall not affect the enforceability of any other 
provision hereof. Waiver of any breach of this License by Symantec shall not be considered a 
waiver of any other or subsequent breach. The licensed software is a unique and valuable 
asset of Symantec and Symantec has the right to seek whatever equitable and legal redress 
which may be available to it for your breach of the provisions of the License. 
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